cvs: phpdoc /en/reference/sdo reference.xml

mfp Wed Jul 20 06:21:34 2005 EDT Modified files: /phpdoc/en/reference/sdo reference.xml Log: Substantial WS change to get one-space indentation, plus <![CDATA in col 1. Handful of typo and punctuation fixes I noticed along the way. No changes to structure, links etc.

http://cvs.php.net/diff.php/phpdoc/en/reference/sdo/reference.xml?r1=1.2&r2=1.3&ty=u Index: phpdoc/en/reference/sdo/reference.xml diff -u phpdoc/en/reference/sdo/reference.xml:1.2 phpdoc/en/reference/sdo/reference.xml:1.3 --- phpdoc/en/reference/sdo/reference.xml:1.2 Tue Jul 19 07:37:37 2005 +++ phpdoc/en/reference/sdo/reference.xml Wed Jul 20 06:21:32 2005 @@ -1,303 +1,331 @@ <?xml version='1.0' encoding='iso-8859-1'?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. --> <reference id="ref.sdo"> - <title>SDO Functions</title> - <titleabbrev>SDO</titleabbrev> + <title>SDO Functions</title> + <titleabbrev>SDO</titleabbrev> - <partintro> - <section id="sdo.intro"> - &reftitle.intro; - <para> - <!-- This warns that the extension is experimental --> - &warn.experimental; - </para> - <para> - Service Data Objects (SDOs) are designed to simplify working with - heterogeneous data whilst also being tailored for service-oriented - applications. Using SDO, developers can uniformly manipulate data for - hetergeneous data sources, such as relational databases and XML. - </para> - <para> - SDOs are based on the concept of disconnected data graphs. A data - graph is a tree structure of data objects, navigable via their containment - references. A containment reference is an aggregation relationship. For - example, a Company data object might consists of a number of Department - data objects and therefore the Company would have a containment - reference to the Departments. A data graph also allows non-containment - references. These are references between data objects within the same - tree. For example, one Employee data object might reference another - to identify a career mentor. - </para> - <para> - The task of connecting an application to a data source is - performed by a Data Access Service (DAS). Applications use a DAS to retrieve - an SDO from a data source. The application can then manipulate the - SDO and use a DAS to write it back to the same, or an alternative, - data source. - </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 - <ulink url='&url.ibm.sdo;'> - Service Data Objects specification - </ulink> -. - </para> - </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 <ulink url='&url.libxml;'>&url.libxml;</ulink>" - </para> - </section> - - - - <section id="sdo.installation"> - &reftitle.install; - <warning> - <para> - An automated installation process using PEAR will be supplied soon. - Meanwhile, you can build the extension manually using the steps below. - </para> - </warning> - <procedure id='sdo.installation.linux.steps'> - <title>Linux intallation steps</title> - <para> - The following instructions describe how to install the SDO extension on Linux. Note, these - steps will also install the - <link linkend="ref.sdo-das-xml">XML Data Access Service</link> - which is packaged as part of this extension. - </para> - <para> - Note, if you built your PHP installation in a different location, using <filename>--prefix</filename>, - then you will need to adjust the <command>./configure</command> steps below accordingly. - </para> - <step> - <para> - Download the SDO extension from the pecl/sdo directory on CVS. - </para> - </step> - <step> - <para> - The SDO and SDO_DAS_XML are implemented as a separate internal 'core' C++ libraries which must be built before building the main extension. - This can be done by using the following steps: - </para> - <procedure id='sdo.installation.linux.substeps'> - <step> - <para> - Go to the core library directory: <command>cd sdo/sdolib</command> - </para> - </step> - <step> - <para> - Run <command>./configure</command> - </para> - </step> - <step> - <para> - The following step is required to ensure <command>g++</command>, and NOT <command>gcc</command> - is used to build the the libraries. - </para> - <para> - Open <filename>libtool</filename> created by the configure script and - change the line which says <command>CC="gcc"</command> to <command>CC="g++"</command>. - </para> - </step> - <step> - <para> - Run <command>make; make install</command> - </para> - </step> - </procedure> - </step> - <step> - <para> - Change to the main extension directory: <command>cd ..</command> - </para> - </step> - <step> - <para> - Run <command>phpize</command>, which will set up the environment to compile both SDO and the XML Data Access Service. - </para> - </step> - <step> - <para> - Next run <command>./configure; make; make install</command>. - </para> - <para> - Note, the compilation process checks for internal 'core' library which was installed in the previous build steps. - </para> - <para> - Note, if you used <filename>--prefix</filename> for the internal 'core' library build, then you will need to add <filename>--with-sdolibs=...</filename> - to the <command>./configure</command> to point to the destination where the libraries were built. - </para> - </step> - <step> - <para> - 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. - </para> - </step> - </procedure> - </section> - - - <section id="sdo.das.table"> - <title>Data Access Services</title> - <para> - The table below lists the currently provided SDO Data Access Services: - <informaltable> - <tgroup cols='2'> - <thead> - <row> - <entry>DAS Name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <link linkend="ref.sdo-das-xml">SDO_DAS_XML</link> - </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. - </entry> - </row> - <row> - <entry> - <link linkend="ref.sdo.das.rel">SDO_DAS_Relational</link> - </entry> - <entry> - A PDO-based Data Access Service supporting reading/writing SDO to relational - data sources. Implements an optimistic concurrency policy for updates. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </section> - - - <section id='sdo.limitations'> - <title>Limitations</title> - <procedure 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. - </para> - </step> - <step> - <para> - The class constants SDO_DAS_ChangeSummary::NONE, SDO_DAS_ChangeSummary::MODIFICATION, - SDO_DAS_ChangeSummary::ADDITION, SDO_DAS_ChangeSummary::DELETION are unavailable, - because of an outstanding problem. - </para> - <para> - As a bypass, the global constants SDO_DAS_CHANGE_SUMMARY_NONE, - SDO_DAS_CHANGE_SUMMARY_MODIFICATION, SDO_DAS_CHANGE_SUMMARY_ADDITION, - SDO_DAS_CHANGE_SUMMARY_DELETION are provided. - </para> - </step> - <step> - <para> - You may see problems when serializing and unserializing graphs which include - non-containment references. We are working on these. - </para> - </step> - </procedure> - <procedure 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> - Abstract types and type derivation. - </para> - </step> - <step> - <para> - Open types. - </para> - </step> - <step> - <para> - Bi-directional relationships. - </para> - </step> - <step> - <para> - Type and property alias names. - </para> - </step> - <step> - <para> - Default property values. - </para> - </step> - <step> - <para> - Read-only properties. - </para> - </step> - <step> - <para> - Model introspection. - </para> - </step> - <step> - <para> - XMLHelper/XSDHelper (the XML DAS provide a lot of this functionality) - </para> - </step> - <step> - <para> - TypeHelper (the SDO_DAS_DataFactory provides this functionality) - </para> - </step> - </procedure> - </section> - - <section 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 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'. - </para> - <para> - <programlisting role="xml"> - <![CDATA[ + <partintro> + <section id="sdo.intro"> + &reftitle.intro; + <para> + <!-- This warns that the extension is experimental --> + &warn.experimental; + </para> + <para> + Service Data Objects (SDOs) are designed to simplify working with + heterogeneous data whilst also being tailored for service-oriented + applications. Using SDO, developers can uniformly manipulate data for + hetergeneous data sources, such as relational databases and XML. + </para> + <para> + SDOs are based on the concept of disconnected data graphs. A data + graph is a tree structure of data objects, navigable via their containment + references. A containment reference is an aggregation relationship. For + example, a Company data object might consists of a number of Department + data objects and therefore the Company would have a containment + reference to the Departments. A data graph also allows non-containment + references. These are references between data objects within the same + tree. For example, one Employee data object might reference another + to identify a career mentor. + </para> + <para> + The task of connecting an application to a data source is + performed by a Data Access Service (DAS). Applications use a DAS to retrieve + an SDO from a data source. The application can then manipulate the + SDO and use a DAS to write it back to the same, or an alternative, + data source. + </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 + <ulink url='&url.ibm.sdo;'> + Service Data Objects specification + </ulink> + </para> + </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 + <ulink url='&url.libxml;'>&url.libxml;</ulink> + . + </para> + </section> + + <section id="sdo.installation"> + &reftitle.install; + <warning> + <para> + An automated installation process using PEAR will be supplied soon. + Meanwhile, you can build the extension manually using the steps below. + </para> + </warning> + <procedure id='sdo.installation.linux.steps'> + <title>Linux intallation steps</title> + <para> + The following instructions describe how to install the SDO extension on Linux. Note, these + steps will also install the + <link linkend="ref.sdo-das-xml">XML Data Access Service</link> + which is packaged as part of this extension. + </para> + <para> + Note, if you built your PHP installation in a different location, using + <filename>--prefix</filename> + , + then you will need to adjust the + <command>./configure</command> + steps below accordingly. + </para> + <step> + <para> + Download the SDO extension from the pecl/sdo directory on CVS. + </para> + </step> + <step> + <para> + The SDO and SDO_DAS_XML are implemented as a separate internal 'core' C++ libraries which must be built before building the main extension. + This can be done by using the following steps: + </para> + <procedure id='sdo.installation.linux.substeps'> + <step> + <para> + Go to the core library directory: + <command>cd sdo/sdolib</command> + </para> + </step> + <step> + <para> + Run + <command>./configure</command> + </para> + </step> + <step> + <para> + The following step is required to ensure + <command>g++</command> + , and NOT + <command>gcc</command> + is used to build the the libraries. + </para> + <para> + Open + <filename>libtool</filename> + created by the configure script and + change the line which says + <command>CC="gcc"</command> + to + <command>CC="g++"</command> + . + </para> + </step> + <step> + <para> + Run + <command>make; make install</command> + </para> + </step> + </procedure> + </step> + <step> + <para> + Change to the main extension directory: + <command>cd ..</command> + </para> + </step> + <step> + <para> + Run + <command>phpize</command> + , which will set up the environment to compile both SDO and the XML Data Access Service. + </para> + </step> + <step> + <para> + Next run + <command>./configure; make; make install</command> + </para> + <para> + Note, the compilation process checks for internal 'core' library which was installed in the previous build steps. + </para> + <para> + Note, if you used + <filename>--prefix</filename> + for the internal 'core' library build, then you will need to add + <filename>--with-sdolibs=...</filename> + to the + <command>./configure</command> + to point to the destination where the libraries were built. + </para> + </step> + <step> + <para> + 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. + </para> + </step> + </procedure> + </section> + + <section id="sdo.das.table"> + <title>Data Access Services</title> + <para> + The table below lists the currently provided SDO Data Access Services: + <informaltable> + <tgroup cols='2'> + <thead> + <row> + <entry>DAS Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <link linkend="ref.sdo-das-xml">SDO_DAS_XML</link> + </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. + </entry> + </row> + <row> + <entry> + <link linkend="ref.sdo.das.rel">SDO_DAS_Relational</link> + </entry> + <entry> + A PDO-based Data Access Service supporting reading/writing SDO to relational + data sources. Implements an optimistic concurrency policy for updates. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </section> + + <section id='sdo.limitations'> + <title>Limitations</title> + <procedure 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. + </para> + </step> + <step> + <para> + The class constants SDO_DAS_ChangeSummary::NONE, SDO_DAS_ChangeSummary::MODIFICATION, + SDO_DAS_ChangeSummary::ADDITION, SDO_DAS_ChangeSummary::DELETION are unavailable, + because of an outstanding problem. + </para> + <para> + As a bypass, the global constants SDO_DAS_CHANGE_SUMMARY_NONE, + SDO_DAS_CHANGE_SUMMARY_MODIFICATION, SDO_DAS_CHANGE_SUMMARY_ADDITION, + SDO_DAS_CHANGE_SUMMARY_DELETION are provided. + </para> + </step> + <step> + <para> + You may see problems when serializing and unserializing graphs which include + non-containment references. We are working on these. + </para> + </step> + </procedure> + <procedure 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> + Abstract types and type derivation. + </para> + </step> + <step> + <para> + Open types. + </para> + </step> + <step> + <para> + Bi-directional relationships. + </para> + </step> + <step> + <para> + Type and property alias names. + </para> + </step> + <step> + <para> + Default property values. + </para> + </step> + <step> + <para> + Read-only properties. + </para> + </step> + <step> + <para> + Model introspection. + </para> + </step> + <step> + <para> + XMLHelper/XSDHelper (the XML DAS provide a lot of this functionality) + </para> + </step> + <step> + <para> + TypeHelper (the SDO_DAS_DataFactory provides this functionality) + </para> + </step> + </procedure> + </section> + + <section 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 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'. + </para> + <para> + <programlisting role="xml"> +<![CDATA[ <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sdo="commonj.sdo" @@ -327,19 +355,19 @@ </xsd:complexType> </xsd:schema> ]]> - </programlisting> - </para> + </programlisting> + </para> - <para> - The instance document below describes a single company, called 'MegaCorp', w - hich 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[ + <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"> @@ -349,245 +377,241 @@ </departments> </company> ]]> - </programlisting> - </para> + </programlisting> + </para> - </section> + </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> - <para> - <example> - <title>Access via Property names</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'. - </para> - <programlisting role="php" id="sdo.examples.propname"> - <![CDATA[ + <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> + <para> + <example> + <title>Access via Property names</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'. + </para> + <programlisting role="php" id="sdo.examples.propname"> +<![CDATA[ <?php $departments = $company->departments; $company->name = 'Acme'; ?> ]]> - </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 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'. - </para> - <programlisting role="php" id="sdo.examples.propindex"> - <![CDATA[ + </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 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'. + </para> + <programlisting role="php" id="sdo.examples.propindex"> +<![CDATA[ <?php $departments = $company[0]; $company[1] = 'Acme'; ?> ]]> - </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 company properties; name, departments and - employeeOfTheMonth. - </para> - <programlisting role="php" id="sdo.examples.doiter"> - <![CDATA[ + </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 company properties; name, departments and + employeeOfTheMonth. + </para> + <programlisting role="php" id="sdo.examples.doiter"> +<![CDATA[ <?php foreach ($company as $name => $value) { ... } ?> ]]> - </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> - </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" id="sdo.examples.mvpiter"> - <![CDATA[ + </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> + </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" 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> - 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[ + </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> + <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. - </para> - <programlisting role="php" id="sdo.examples.nestedprop"> - <![CDATA[ + </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. + </para> + <programlisting role="php" id="sdo.examples.nestedprop"> +<![CDATA[ <?php $dept_name = $company->departments[0]->name; $company->departments[0]->name = 'Emerging Technologies'; ?> ]]> - </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[ + </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> - <programlisting role="php" id="sdo.examples.chainarray"> - <![CDATA[ + </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> + <programlisting role="php" id="sdo.examples.chainarray"> +<![CDATA[ <?php $dept_name = $company['departments'][0]['name']; $company['departments'][0]['name'] = 'Emerging Technologies'; ?> ]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>XPath Navigation</title> - <para> - We can use XPath expressions to navigate the data object - instance structure. 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. - </para> - <programlisting role="php" id="sdo.examples.xpathnav"> - <![CDATA[ + </programlisting> + </example> + </para> + + <para> + <example> + <title>XPath Navigation</title> + <para> + We can use XPath expressions to navigate the data object + instance structure. 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. + </para> + <programlisting role="php" id="sdo.examples.xpathnav"> +<![CDATA[ <?php $jane_doe = $company["departments[1]/employees[2]"]; $jane_doe = $company["departments.0/employees.1"]; ?> ]]> - </programlisting> - </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" id="sdo.examples.xpathquery"> - <![CDATA[ + </programlisting> + </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" id="sdo.examples.xpathquery"> +<![CDATA[ <?php $ad_tech_mgr = $company["departments[name=\"Advanced Technologoies\"]/employees[manager=\"true\"]"]; ?> ]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Creating child data object</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" id="sdo.examples.create"> - <![CDATA[ + </programlisting> + </example> + </para> + + <para> + <example> + <title>Creating child data object</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" id="sdo.examples.create"> +<![CDATA[ <?php $ad_tech_dept = $company["departments[name=\"Advanced Technologoies\"]"]; $new_hire = $ad_tech_dept->createDataObject('employees'); @@ -596,71 +620,71 @@ $new_hire->manager = false; ?> ]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Unset referenced data object</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 removes the 'employeeOfTheMonth' from the company. - If this were a containment reference 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" id="sdo.examples.unsetrefdo"> - <![CDATA[ + </programlisting> + </example> + </para> + + <para> + <example> + <title>Unset referenced data object</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 removes the 'employeeOfTheMonth' from the company. + If this were a containment reference 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" id="sdo.examples.unsetrefdo"> +<![CDATA[ <?php if (isset($company->employeeOfTheMonth) { unset($company->employeeOfTheMonth); } ?> ]]> - </programlisting> - </example> - </para> - </section> - - <section 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[ + </programlisting> + </example> + </para> + </section> + + <section 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"> @@ -674,17 +698,17 @@ </xsd:complexType> </xsd:schema> ]]> - </programlisting> - </para> + </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[ + <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 @@ -696,175 +720,173 @@ 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>Sequnece 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" id="sdo.examples.seqinterface"> - <![CDATA[ + </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" 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" id="sdo.examples.getsetseq"> - <![CDATA[ + </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" 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" id="sdo.examples.seqiter"> - <![CDATA[ + </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" 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" id="sdo.examples.seqvsdo"> - <![CDATA[ + </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" 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" id="sdo.examples.seqadd"> - <![CDATA[ + </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" id="sdo.examples.seqadd"> +<![CDATA[ <?php // Append a firstName value to the sequence // value: 'Smith' @@ -892,403 +914,373 @@ $letters_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). - Sequence behaves like a contiguous list and therefore removing - from the middle results in entries at higher indices being shifted - down. The following example tests to see if the first sequence - element is set and unsets it if is. - </para> - <programlisting role="php" id="sdo.examples.seqremove"> - <![CDATA[ + </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). + Sequence behaves like a contiguous list and therefore removing + from the middle results in entries at higher indices being shifted + down. The following example tests to see if the first sequence + element is set and unsets it if is. + </para> + <programlisting role="php" id="sdo.examples.seqremove"> +<![CDATA[ <?php if (isset($letter_seq[0]) { unset($letter_seq[0]); } ?> ]]> - </programlisting> - </example> - </para> + </programlisting> + </example> + </para> + + </section> + + <!-- class definition section --> + <section id='sdo.classes'> + &reftitle.classes; + <para> + SDO consists of two set of interfaces. The first set covers those + interfaces for use by SDO client applications. These are identified by + the package prefix 'SDO_'. The second set is those for use by Data + Access Service implementations and are identified by the package prefix + 'SDO_DAS_'. The majority of SDO users will not need to use or understand + the 'SDO_DAS_' interfaces. + </para> + + <section id='sdo.class.sdo-apis'> + <title>SDO Application Programmer Interface</title> + + <section id='sdo.class.sdo-dataobject'> + <title> + <classname>SDO_DataObject</classname> + </title> + <para> + The main interface through which data objects are manipulated. In + addition to the methods below, SDO_DataObject extends the + ArrayAccess, SDO_PropertyAccess (defines + <function>__get</function> + / + <function>__set</function> + methods for property access overloading), Iterator, and + Countable interfaces. + </para> + <section id='sdo.class.SDO_DataObject.methods'> &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DataObject-getType'>getType</link> - get the type of a data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DataObject-getSequence'>getSequnece</link> - get the sequence for the data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DataObject-createDataObject'>createDataObject</link> - create a child data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DataObject-clear'>clear</link> - unset the properties of a data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DataObject-getContainer'>getContainer</link> - get the container (also known as 'parent') of this data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DataObject-getContainmentPropertyName'>getContainmentPropertyName</link> - get the name by which the parent refers to this data object + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section id='sdo.class.sdo-sequence'> + <title> + <classname>SDO_Sequence</classname> + </title> + <para> + The interface through which sequenced data objects can be accessed in + order to preserve ordering across a data object's properties and to allow + unstructured text. SDO_Sequence preserves contiguous indices and + therefore inserting or removing elements may results in other elements shifted up or + down. In addition to the methods below, SDO_Sequence extends the + ArrayAccess, Iterator and Countable interface. + </para> + <section id='sdo.class.SDO_Sequence.methods'> + &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-Sequence-getPropertyIndex'>getPropertyIndex</link> - get the property index for a given sequence index + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-Sequence-getPropertyName'>getPropertyName</link> - get the property name for a given sequence index + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-Sequence-move'>move</link> - move an element from one property index to another + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-Sequence-insert'>insert</link> - insert a new value into the sequence + </para> + </listitem> + </itemizedlist> + </section> </section> + <section id='sdo.class.sdo-list'> + <title> + <classname>SDO_List</classname> + </title> + <para> + The interface through which many-valued properties are manipulated. + In addition to the method defined below, SDO_List extends ArrayAccess, + Iterator and Coutable. SDO_List preserves contiguous indices and + therefore inserting or removing elements may results in other elements + shifted up or down. + </para> + <section id='sdo.class.SDO-List.methods'> + &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-List-insert'>insert</link> - insert a new value into the list + </para> + </listitem> + </itemizedlist> + </section> + </section> - <!-- class definition section --> - <section id='sdo.classes'> - &reftitle.classes; - <para> - SDO consists to two set of interfaces. The first set covers those - interfaces for use by SDO client applications. These are identified by - the package prefix 'SDO_'. The second set is those for use by Data - Access Service implementations and are identified by the package prefix - 'SDO_DAS_'. The majority of SDO users will not need to use or understand - the 'SDO_DAS_' interfaces. - </para> - - <section id='sdo.class.sdo-apis'> - <title>SDO Application Programmer Interface</title> - - - <section id='sdo.class.sdo-dataobject'> - <title> - <classname>SDO_DataObject</classname> - </title> - <para> - The main interface through which data objects are manipulated. In - addition to the methods below, SDO_DataObject extends the - ArrayAccess, SDO_PropertyAccess (defines - <function>__get</function> -/ - <function>__set</function> - methods for property access overloading), Iterator, and - Countable interfaces - </para> - <section id='sdo.class.SDO_DataObject.methods'> &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DataObject-getType'>getType</link> - - get the type of a data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DataObject-getSequence'>getSequnece</link> - - get the sequence for the data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DataObject-createDataObject'>createDataObject</link> - - create a child data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DataObject-clear'>clear</link> - - unset the properties of a data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DataObject-getContainer'>getContainer</link> - - get the container (also known as 'parent') of this data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DataObject-getContainmentPropertyName'>getContainmentPropertyName</link> - - get the name by which the parent refers to this data object - </para> - </listitem> - </itemizedlist> - </section> - </section> - - <section id='sdo.class.sdo-sequence'> - <title> - <classname>SDO_Sequence</classname> - </title> - <para> - The interface through which sequenced data objects can be accessed in - order to preserve ordering across a data object's properties and to allow - unstructured text. SDO_Sequence preserves contiguous indices and - therefore inserting or removing elements may results in other elements shifted up or - down. In addition to the methods below, SDO_Sequence extends the - ArrayAccess, Iterator and Countable interface. - </para> - <section id='sdo.class.SDO_Sequence.methods'> - &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-Sequence-getPropertyIndex'>getPropertyIndex</link> - - get the property index for a given sequence index - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-Sequence-getPropertyName'>getPropertyName</link> - - get the property name for a given sequence index - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-Sequence-move'>move</link> - - move an element from one property index to another - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-Sequence-insert'>insert</link> - - insert a new value into the sequence - </para> - </listitem> - </itemizedlist> - </section> - </section> - - <section id='sdo.class.sdo-list'> - <title> - <classname>SDO_List</classname> - </title> - <para> - The interface through which many-valued properties are manipulated. - In addition to the method defined below, SDO_List extends ArrayAccess, - Iterator and Coutable. SDO_List preserves contiguous indices and - therefore inserting or removing elements may results in other elements - shifted up or down. - </para> - <section id='sdo.class.SDO-List.methods'> - &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-List-insert'>insert</link> - - insert a new value into the list - </para> - </listitem> - </itemizedlist> - </section> - </section> - - <section id='sdo.class.sdo-datafactory'> - <title> - <classname>SDO_DataFactory</classname> - </title> - <para> - The interface through which data objects can be created. A Data - Access Service is responsible for populating the model (i.e. configuring - the data factory with the type and structure information for the data - objects it can create.) for the factory and - can then optionally return an instance of, or implement, the - SDO_DataFactory interface. - </para> - <section id='sdo.class.SDO-DataFactory.methods'> - &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DataFactory-create'>create</link> - - create a new data object - </para> - </listitem> - </itemizedlist> - </section> - </section> - </section> - - - <section id='sdo.class.sdo-das-spis'> - <title> - SDO Data Access Service Developer Interfaces - </title> - - - <section id='sdo.class.sdodas-dataobject'> - <title> - <classname>SDO_DAS_DataObject</classname> - </title> - <para> - The interface through which a Data Access Service can access a data object's - <link linkend='sdo.class.sdodas-changesummary'>SDO_DAS_ChangeSummary.</link> - The change summary is used by the Data Access Service to check for conflicts - when applying changes back to a data source. - </para> - <section id='sdo.class.SDO_DAS_DataObject.methods'> &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DAS-DataObject-getChangeSummary'>getChangeSummary</link> - - get the change summary for a data object - </para> - </listitem> - - </itemizedlist> - </section> - </section> - - - <section id='sdo.class.sdodas-changesummary'> - <title> - <classname>SDO_DAS_ChangeSummary</classname> - </title> - <para> - The interface through which the change history of a data - object is accessed. The change summary holds information for any - modifications on a data object which occurred since logging - was activated. In the case of deletions and modifications, the old - values are also held in the change summary. - </para> - <para> - If logging is no longer active - then the change summary only hold changes made up to the point when - logging was deactivated. Reactivating logging clears the change summary. - This is useful when a set of changes have been written out by a - DAS and the data object is to be reused. - </para> - <section id='sdo.class.SDO_DAS_ChangeSummary.methods'> - &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-beginLogging'>beginLogging</link> - - begin logging changes made to a data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-endLogging'>endLogging</link> - - end logging changes made to a data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-isLogging'>isLogging</link> - - test to see if change logging is on - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-getChangedDataObjects'>getChangedDataObjects</link> - - get a list of the data objects which have been changed - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-getChangeType'>getChangeType</link> - - get the type of change which has been made to a data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-getOldValues'>getOldValues</link> - - get a list of old values for a data object - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-ChangeSummary-getOldContainer'>getOldContainer</link> - - get the old container data object for a deleted data object - </para> - </listitem> - </itemizedlist> - </section> - </section> - - <section id='sdo.class.sdodas-setting'> - <title> - <classname>SDO_DAS_Setting</classname> - </title> - <para> - The interface through which the old value for a property is - accessed. A list of settings is returned by the change summary method - <link linkend='function.SDO-DAS-ChangeSummary-getOldValues'> - <function>getOldValues</function> - </link> + <section id='sdo.class.sdo-datafactory'> + <title> + <classname>SDO_DataFactory</classname> + </title> + <para> + The interface through which data objects can be created. A Data + Access Service is responsible for populating the model (i.e. configuring + the data factory with the type and structure information for the data + objects it can create.) for the factory and + can then optionally return an instance of, or implement, the + SDO_DataFactory interface. + </para> + <section id='sdo.class.SDO-DataFactory.methods'> + &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DataFactory-create'>create</link> - create a new data object + </para> + </listitem> + </itemizedlist> + </section> + </section> + </section> + + + <section id='sdo.class.sdo-das-spis'> + <title> + SDO Data Access Service Developer Interfaces + </title> + + + <section id='sdo.class.sdodas-dataobject'> + <title> + <classname>SDO_DAS_DataObject</classname> + </title> + <para> + The interface through which a Data Access Service can access a data object's + <link linkend='sdo.class.sdodas-changesummary'>SDO_DAS_ChangeSummary.</link> + The change summary is used by the Data Access Service to check for conflicts + when applying changes back to a data source. + </para> + <section id='sdo.class.SDO_DAS_DataObject.methods'> &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DAS-DataObject-getChangeSummary'>getChangeSummary</link> - get the change summary for a data object + </para> + </listitem> + + </itemizedlist> + </section> + </section> + + + <section id='sdo.class.sdodas-changesummary'> + <title> + <classname>SDO_DAS_ChangeSummary</classname> + </title> + <para> + The interface through which the change history of a data + object is accessed. The change summary holds information for any + modifications on a data object which occurred since logging + was activated. In the case of deletions and modifications, the old + values are also held in the change summary. + </para> + <para> + If logging is no longer active + then the change summary only hold changes made up to the point when + logging was deactivated. Reactivating logging clears the change summary. + This is useful when a set of changes have been written out by a + DAS and the data object is to be reused. + </para> + <section id='sdo.class.SDO_DAS_ChangeSummary.methods'> + &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-beginLogging'>beginLogging</link> - begin logging changes made to a data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-endLogging'>endLogging</link> - end logging changes made to a data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-isLogging'>isLogging</link> - test to see if change logging is on + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-getChangedDataObjects'>getChangedDataObjects</link> - get a list of the data objects which have been changed + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-getChangeType'>getChangeType</link> - get the type of change which has been made to a data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-getOldValues'>getOldValues</link> - get a list of old values for a data object + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-ChangeSummary-getOldContainer'>getOldContainer</link> - get the old container data object for a deleted data object + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section id='sdo.class.sdodas-setting'> + <title> + <classname>SDO_DAS_Setting</classname> + </title> + <para> + The interface through which the old value for a property is + accessed. A list of settings is returned by the change summary method + <link linkend='function.SDO-DAS-ChangeSummary-getOldValues'> + <function>getOldValues</function> + </link> . - </para> - <section id='sdo.class.SDO_DAS_Setting.methods'> - &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DAS-Setting-getPropertyIndex'>getPropertyIndex</link> - - get the property index for the changed property - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-Setting-getPropertyName'>getPropertyName</link> - - get the property name for the changed property - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-Setting-getValue'>getValue</link> - - get the old value for the changed property - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-Setting-getListIndex'>getListIndex</link> - - get the list index for the old value if it was part of + </para> + <section id='sdo.class.SDO_DAS_Setting.methods'> + &reftitle.methods; + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DAS-Setting-getPropertyIndex'>getPropertyIndex</link> - get the property index for the changed property + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-Setting-getPropertyName'>getPropertyName</link> - get the property name for the changed property + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-Setting-getValue'>getValue</link> - get the old value for the changed property + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-Setting-getListIndex'>getListIndex</link> - get the list index for the old value if it was part of a many-valued property - </para> - </listitem> - <listitem> - <para> - <link linkend='function.SDO-DAS-Setting-isSet'>isSet</link> - - test to see if the property was set prior to being modified - </para> - </listitem> - </itemizedlist> - </section> - </section> - - <section id='sdo.class.sdodas-datafactory'> - <title> - <classname>SDO_DAS_DataFactory</classname> - </title> - <para> - The interface for constructing the model for an SDO_DataObject. - The SDO_DAS_DataFactory is an abstract class providing a static - method which returns a concrete data factory implementation. - The implementation is used by Data Access Services to create an SDO model from their model. - For example, a Relational Data Access Service might create and populate an - SDO_DAS_DataFactory model based on a schema for a relational database. - </para> - <section id='sdo.class.SDO_DAS_DataFactory.methods'> + </para> + </listitem> + <listitem> + <para> + <link linkend='function.SDO-DAS-Setting-isSet'>isSet</link> - test to see if the property was set prior to being modified + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section id='sdo.class.sdodas-datafactory'> + <title> + <classname>SDO_DAS_DataFactory</classname> + </title> + <para> + The interface for constructing the model for an SDO_DataObject. + The SDO_DAS_DataFactory is an abstract class providing a static + method which returns a concrete data factory implementation. + The implementation is used by Data Access Services to create an SDO model from their model. + For example, a Relational Data Access Service might create and populate an + SDO_DAS_DataFactory model based on a schema for a relational database. + </para> + <section id='sdo.class.SDO_DAS_DataFactory.methods'> &reftitle.methods; - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DAS-DataFactory-getDataFactory'>getDataFactory</link> - - static methods for getting a concrete data factory instance - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DAS-DataFactory-addType'>addType</link> - - add a new type to the SDO model - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para> - <link linkend='function.SDO-DAS-DataFactory-addPropertyToType'>addPropertyToType</link> - - add a new property to a type definition in the SDO model - </para> - </listitem> - </itemizedlist> - </section> - </section> - </section> + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DAS-DataFactory-getDataFactory'>getDataFactory</link> - static methods for getting a concrete data factory instance + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DAS-DataFactory-addType'>addType</link> - add a new type to the SDO model + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para> + <link linkend='function.SDO-DAS-DataFactory-addPropertyToType'>addPropertyToType</link> - add a new property to a type definition in the SDO model + </para> + </listitem> + </itemizedlist> + </section> </section> + </section> + </section> - &reference.sdo.constants; + &reference.sdo.constants; - </partintro> + </partintro> &reference.sdo.functions;