mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 08:58:56 +00:00
First check in of documentation for SDO Relational DAS
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@190982 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Matthew Peters
parent
52960cd59b
commit
0c7b03e66b
7 changed files with 1813 additions and 0 deletions
32
reference/sdodasrel/constants.xml
Normal file
32
reference/sdodasrel/constants.xml
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
<?xml version='1.0' encoding='iso-8859-1'?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
|
||||
<section id="sdodasrel.constants">
|
||||
<!-- &reftitle.constants;
|
||||
&extension.constants;
|
||||
-->
|
||||
<para>
|
||||
The Relational DAS introduces no predefined constants.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
4
reference/sdodasrel/functions.xml
Normal file
4
reference/sdodasrel/functions.xml
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
&reference.sdodasrel.functions.SDO-DAS-Relational-applyChanges;
|
||||
&reference.sdodasrel.functions.SDO-DAS-Relational-construct;
|
||||
&reference.sdodasrel.functions.SDO-DAS-Relational-createRootDataObject;
|
||||
&reference.sdodasrel.functions.SDO-DAS-Relational-executeQuery;
|
||||
|
|
@ -0,0 +1,130 @@
|
|||
<?xml version='1.0' encoding='iso-8859-1'?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<refentry id="function.SDO-DAS-Relational-applyChanges">
|
||||
<refnamediv>
|
||||
<refname>SDO_DAS_Relational::applyChanges</refname>
|
||||
<refpurpose>
|
||||
Applies the changes made to a data graph back to the database.
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<type>void</type>
|
||||
<methodname>SDO_DAS_Relational::applyChanges</methodname>
|
||||
<methodparam>
|
||||
<type>PDO</type>
|
||||
<parameter>database_handle</parameter>
|
||||
</methodparam>
|
||||
<methodparam>
|
||||
<type>string</type>
|
||||
<parameter>root_data_object</parameter>
|
||||
</methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
&warn.experimental.func;
|
||||
|
||||
|
||||
<para>
|
||||
Given a datagraph and a PDO database handle, examines the change summary in the datagraph and applies the changes to the database.
|
||||
The changes that it can apply can be creations of data objects, deletes of data objects, and modifications to properties of data objects.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>PDO_database_handle</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Constructed using the PDO extension. A typical line to construct a PDO database handle might look like this:
|
||||
<programlisting role="php" id="sdo.das.rel.ac.examples.pdo">
|
||||
<![CDATA[
|
||||
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>root_data_object</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The special root object which is at the top of every SDO data graph.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
None.
|
||||
Note however that the datagraph that was passed is still intact and usable.
|
||||
Furthermore, if data objects were created and written back to a table with autogenerated primary keys, then those primary keys will now be set in the data objects.
|
||||
If the changes were successfully written, then the change summary associated with the datagraph will have been cleared, so that it is possible to now make further changes to the data graph and apply those changes in turn.
|
||||
In this way it is possible to work with the same data graph and apply changes repeatedly.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="exceptions">
|
||||
&reftitle.exceptions;
|
||||
<para>
|
||||
<function>SDO_DAS_Relational::applyChanges</function>
|
||||
can throw an SDO_DAS_Relational_Exception if it is unable to apply all the changes correctly.
|
||||
</para>
|
||||
<para>
|
||||
The Relational DAS starts a database transaction before beginning to apply the changes and will commit the transaction only if they are all successful.
|
||||
The Relational DAS generates qualified update and delete statements which contain a where clause that specifies that the row to be updated or deleted must contain the same values that it did when the data was first retrieved.
|
||||
This is how the the optimistic concurrency is implemented.
|
||||
If any of the qualified update or delete statements fails to update or delete their target row, it may be because the data has been altered in the database in the meantime.
|
||||
In any event, if any update fails for any reason, the transaction is rolled back and an exception thrown.
|
||||
The exception will contain the generated SQL statement that failed.
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
The Relational DAS also catches any PDO exceptions and obtains PDO diagnostic information which it includes in an SDO_DAS_Relational_Exception which it then throws.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
Please see the
|
||||
<link linkend='sdo.das.rel.examples'>Examples</link> section in the general information about the Relational DAS
|
||||
for many examples of calling this method.
|
||||
Please see also the section on
|
||||
<link linkend='sdo.das.rel.tracing'>Tracing</link> to see how you can see what SQL statements are generated by the Relational DAS.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
145
reference/sdodasrel/functions/SDO-DAS-Relational-construct.xml
Normal file
145
reference/sdodasrel/functions/SDO-DAS-Relational-construct.xml
Normal file
|
|
@ -0,0 +1,145 @@
|
|||
<?xml version='1.0' encoding='iso-8859-1'?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<refentry id="function.SDO-DAS-Relational-construct">
|
||||
<refnamediv>
|
||||
<refname>SDO_DAS_Relational::__construct</refname>
|
||||
<refpurpose>
|
||||
Creates an instance of a Relational Data Access Service
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<type>SDO_DAS_Relational</type>
|
||||
<methodname>SDO_DAS_Relational::__construct</methodname>
|
||||
<methodparam>
|
||||
<type>array</type>
|
||||
<parameter>database_metadata</parameter>
|
||||
</methodparam>
|
||||
<methodparam choice="opt">
|
||||
<type>string</type>
|
||||
<parameter>application_root_type</parameter>
|
||||
</methodparam>
|
||||
<methodparam choice="opt">
|
||||
<type>array</type>
|
||||
<parameter>SDO_containment_references_metadata</parameter>
|
||||
</methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
&warn.experimental.func;
|
||||
|
||||
|
||||
|
||||
<para>
|
||||
Constructs an instance of a Relational Data Access Service from the passed metadata.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>database_metadata</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An array containing one or more table definitions, each of which is an associative array containing the keys
|
||||
<varname>name</varname>
|
||||
,
|
||||
<varname>columns</varname>
|
||||
,
|
||||
<varname>PK</varname>
|
||||
, and optionally,
|
||||
<varname>FK</varname>
|
||||
.
|
||||
For a full discussion of the metadata, see the
|
||||
<link linkend='sdo.das.rel.metadata'>metadata</link>
|
||||
section in the general information about the Relational DAS.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>application_root_type</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The root of each data graph is an object of a special root type and the application data objects come below that.
|
||||
Of the various application types in the SDO model, one has to be the the application type immediately below the root of the data graph.
|
||||
If there is only one table in the database metadata, so the application root type can be inferred, this argument can be omitted.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>SDO_containment_references_metadata</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An array containing one or more definitions of a containment relation, each of which is an associative array containing the keys
|
||||
<varname>parent</varname>
|
||||
and
|
||||
<varname>child</varname>
|
||||
.
|
||||
The containment relations describe how the types in the model are connected to form a tree.
|
||||
The type specified as the application root type must be present as one of the parent types in the containment references.
|
||||
If the application only needs to work with one table at a time, and there are no containment relations in the model, this argument can be omitted.
|
||||
For a full discussion of the metadata, see the
|
||||
<link linkend='sdo.das.rel.metadata'>metadata</link>
|
||||
section in the general information about the Relational DAS.
|
||||
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
Returns an SDO_DAS_Relational object on success.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
|
||||
<refsect1 role="exceptions">
|
||||
&reftitle.exceptions;
|
||||
<para>
|
||||
<function>SDO_DAS_Relational::construct</function>
|
||||
throws a SDO_DAS_Relational_Exception if any problems are found in the metadata.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
For a full discussion of the metadata, see the
|
||||
<link linkend='sdo.das.rel.metadata'>metadata</link>
|
||||
section in the general information about the Relational DAS.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
<?xml version='1.0' encoding='iso-8859-1'?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<refentry id="function.SDO-DAS-Relational-createRootDataObject">
|
||||
<refnamediv>
|
||||
<refname>SDO_DAS_Relational::createRootDataObject</refname>
|
||||
<refpurpose>
|
||||
Returns the special root object in an otherwise empty data graph. Used when creating a data graph from scratch.
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<type>special root object</type>
|
||||
<methodname>SDO_DAS_Relational::createRootDataObject</methodname>
|
||||
<void/>
|
||||
</methodsynopsis>
|
||||
|
||||
&warn.experimental.func;
|
||||
|
||||
|
||||
<para>
|
||||
Returns the special root object at the top of an otherwise empty data graph.
|
||||
This call is used when the application wants to create a data graph from scratch, without having called
|
||||
<function>executeQuery</function>
|
||||
to create a data graph.
|
||||
</para>
|
||||
<para>
|
||||
The special root object has one multi-valued containment property, with a name of the application root type that was passed when the Relational DAS was constructed.
|
||||
The property can take values of only that type.
|
||||
The only thing that the application can usefully do with the root type is to call
|
||||
<function>createDataObject</function>
|
||||
on it, passing the name of the application root type,
|
||||
in order to create a data object of their own application type.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<para>
|
||||
None.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
The root object.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="exceptions">
|
||||
&reftitle.exceptions;
|
||||
<para>
|
||||
None.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
Please see the
|
||||
<link linkend='sdo.das.rel.examples'>Examples</link> section in the general information about the Relational DAS
|
||||
for many examples of calling this method.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
|
|
@ -0,0 +1,160 @@
|
|||
<?xml version='1.0' encoding='iso-8859-1'?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
<refentry id="function.SDO-DAS-Relational-executeQuery">
|
||||
<refnamediv>
|
||||
<refname>SDO_DAS_Relational::executeQuery</refname>
|
||||
<refpurpose>
|
||||
Executes a given SQL query against a relational database and returns the results as a normalised data graph.
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<type>data graph</type>
|
||||
<methodname>SDO_DAS_Relational::executeQuery</methodname>
|
||||
<methodparam>
|
||||
<type>PDO</type>
|
||||
<parameter>database_handle</parameter>
|
||||
</methodparam>
|
||||
<methodparam>
|
||||
<type>string</type>
|
||||
<parameter>SQL_statement</parameter>
|
||||
</methodparam>
|
||||
<methodparam choice="opt">
|
||||
<type>array</type>
|
||||
<parameter>column_specifier</parameter>
|
||||
</methodparam>
|
||||
</methodsynopsis>
|
||||
|
||||
&warn.experimental.func;
|
||||
|
||||
|
||||
<para>
|
||||
Executes a given query against the relational database, using the supplied PDO database handle.
|
||||
Uses the model that it built from the the metadata to interpret the result set.
|
||||
Returns a data graph.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>PDO_database_handle</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Constructed using the PDO extension. A typical line to construct a PDO database handle might look like this:
|
||||
<programlisting role="php" id="sdo.das.rel.eq.examples.pdo">
|
||||
<![CDATA[
|
||||
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>SQL_statement</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The SQL statement to be executed against the database.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>column_specifier</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The Relational DAS needs to examine the result set and for every column, know which table and which column of that table it came from.
|
||||
In some circumstances it can find this information for itself, but sometimes it cannot.
|
||||
In these cases a column specifier is needed, which is an array that identifies the columns.
|
||||
Each entry in the array is simply a string in the form
|
||||
<varname>table-name.column_name</varname>
|
||||
.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The column specifier is needed when there are duplicate column names in the database metadata,
|
||||
For example, in the database used within the examples, all the tables have both a
|
||||
<varname>id</varname>
|
||||
and a
|
||||
<varname>name</varname>
|
||||
column.
|
||||
When the Relational DAS fetches the result set from PDO it can do so with the PDO_FETCH_ASSOC attribute, which will cause the columns in the results set to be labelled with the column name, but will not distinguish duplicates.
|
||||
So this will only work when there are no duplicates possible in the results set.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To summarise, specify a column specifier array whenever there is any uncertainty about which column could be from which table and
|
||||
only omit it when every column name in the database metadata is unique.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the examples in the
|
||||
<link linkend='sdo.das.rel.examples'>Examples</link>
|
||||
use a column specifier.
|
||||
There is one example in the <filename>Scenarios</filename> directory of the installation that does not: that which works with just the employee table, and because it works with just one table, there can not exist duplicate column names.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
Returns a data graph. Specifically, it returns a root object of a special type.
|
||||
Under this root object will be the data from the result set.
|
||||
The root object will have a multi-valued containment property with the same name as the application root type specified on the constructor,
|
||||
and that property will contain one or more data objects of the application root type.
|
||||
</para>
|
||||
<para>
|
||||
In the event that the query returns no data, the special root object will still be returned but the containment property for the application root type will be empty.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="exceptions">
|
||||
&reftitle.exceptions;
|
||||
<para>
|
||||
<function>SDO_DAS_Relational::executeQuery</function>
|
||||
can throw an SDO_DAS_Relational_Exception if it is unable to construct the data graph correctly.
|
||||
This can occur for a number of reasons: for example if it finds that it does not have primary keys in the result set for all the objects.
|
||||
It also catches any PDO exceptions and obtains PDO diagnostic information which it includes in an SDO_DAS_Relational_Exception which it then throws.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
Please see the
|
||||
<link linkend='sdo.das.rel.examples'>Examples</link> section in the general information about the Relational DAS
|
||||
for many examples of calling this method.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
1251
reference/sdodasrel/reference.xml
Normal file
1251
reference/sdodasrel/reference.xml
Normal file
File diff suppressed because it is too large
Load diff
Loading…
Reference in a new issue