Several edits for spelling, punctuation, making the existing text read more clearly. No changes to the meaning, no new material.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@191544 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Matthew Peters 2005-07-26 14:02:08 +00:00
parent 4a933fee66
commit 88cb6dc07c

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<reference id="ref.sdo.das.rel">
<title>SDO Relational Data Access Service Functions</title>
@ -13,7 +13,7 @@
&warn.experimental;
</para>
<para>
In order to use the Relational Data Acces Service for
In order to use the Relational Data Access Service for
Service Data Objects,
you will need to understand some of the concepts behind SDO:
the data graph, the data object, the disconnected way of working,
@ -67,15 +67,15 @@
is a normalised data graph containing all the data from the result set.
For a query that returns data obtained from a number of tables,
this graph will contain a number of data objects,
linked by containment references.
There may also be non-containment references within the data.
linked by SDO containment references.
There may also be SDO non-containment references within the data.
</para>
<para>
Once the query has been executed and the data graph constructed,
there is no need for either the Relational DAS or the
database connection. There are no locks held on the database.
Both the Relational Das and the PDO database connection can be
there is no need for either that instance of the the Relational DAS or
the database connection. There are no locks held on the database.
Both the Relational DAS and the PDO database connection can be
garbage collected.
</para>
</step>
@ -86,7 +86,7 @@
into the PHP session and so may have a lifetime beyond just
one client-server interaction. Data objects can be created
and added to the graph, the data objects already in the graph
can be deleted, and they can be modified.
can be deleted, and data objects in the graph can be modified.
</para>
</step>
<step>
@ -97,11 +97,11 @@
method of the Relational DAS. For this, another instance
of the Relational DAS must be constructed, using the
same metadata, and another connection to the database obtained.
These, plus the data graph itself, are passed to
The connection and the data graph are passed to
<function>applyChanges</function>.
At this point the Relational DAS examines the change summary
and generates the necessary INSERT, UPDATE and DELETE SQL statements
to apply the changes. The UPDATE and DELETE statements are qualified
to apply the changes. Any UPDATE and DELETE statements are qualified
with the original values of the data so that should the data have
changed in the database in the meantime this will be detected.
Assuming no such collisions have occurred the changes will be
@ -240,7 +240,7 @@ require_once 'SDO/DAS/Relational.php';
<para>
The Relational DAS is constructed with metadata that defines the
relational database and how it should be mapped to SDO.
The first long section describes this metadata and how to
The long section that follows describes this metadata and how to
construct the Relational DAS. The examples that follow it all assume that
this metadata is in an included php file.
</para>
@ -326,7 +326,7 @@ require_once 'SDO/DAS/Relational.php';
<entry>FK</entry>
<entry>An array with two entries, 'from' and 'to', which define
a column containing a foreign key, and a table to which the foreign
key points to. If there are no foreign keys in the table then the
key points. If there are no foreign keys in the table then the
'FK' entry does not need to be specified. Only one foreign key
can be specified. Only a foreign key pointing to the primary key
of a table can be specified.
@ -437,16 +437,17 @@ $database_metadata = array($company_table, $department_table, $employee_table);
<para>
There are a few simple rules to be followed when constructing the
database metadata
database metadata:
</para>
<itemizedlist>
<listitem>
<para>
All tables must have primary keys and they must be specified in
the metadata. Without primary keys it is not possible to keep track
of object identities. As you see from the SQL statements, primary
keys can be auto-generated, that is assigned by the database when
All tables must have primary keys, and the primary keys must be
specified in the metadata. Without primary keys it is not possible
to keep track of object identities. As you can see from the SQL
statements that create the tables, primary keys can be
auto-generated, that is, generated and assigned by the database when
a record is inserted. In this case the auto-generated primary key
is obtained from the database and inserted into the data object
immediately after the row is inserted into the database.
@ -461,7 +462,7 @@ $database_metadata = array($company_table, $department_table, $employee_table);
application did not want to access with SDO, this need not be
specified in the metadata. On the other hand it would have done
no harm to specify it: if specified in the metadata but never
retrieved, or set by the application, then the unused column
retrieved, or assigned to by the application, then the unused column
will not affect anything.
</para>
</listitem>
@ -491,7 +492,7 @@ $database_metadata = array($company_table, $department_table, $employee_table);
The Relational DAS uses the database metadata to form most of the
SDO model. For each table in the database metadata, an SDO type
is defined. Each column which can represent a primitive value
(this is columns which are not defined as foreign keys) are added
(columns which are not defined as foreign keys) are added
as properties to the SDO type.
</para>
<para>
@ -568,13 +569,12 @@ $SDO_reference_metadata = array($department_reference, $employee_reference);
<varname>dept_id</varname>
column in the employee table) are interpreted as supporting the
SDO containment references.
Each containment reference mentioned in the SDO containment references
metadata must have a corresponding foreign key in the database and
defined in the database metadata. The values of the foreign key
columns for containment references do not appear in the data objects,
instead they are represented by the containment reference from the
parent to the child.
So the
Each containment reference mentioned in the SDO containment references
metadata must have a corresponding foreign key present in the
database and defined in the database metadata. The values of the
foreign key columns for containment references do not appear in the
data objects, instead they are represented by the containment reference
from the parent to the child. So the
<varname>co_id</varname>
column in the department row in the database, for example, does not
appear as a property on the department type, but instead as a
@ -590,15 +590,17 @@ $SDO_reference_metadata = array($department_reference, $employee_reference);
<para>
The third foreign key in this example, the
<varname>employee_of_the_month</varname>
,
is handled differently.
This is not mentioned in the SDO containment references metadata.
As a consequence this is interpreted in the second way: it becomes
a single-valued non-containment reference on the company object
which can be assigned SDO data object references of the employee type.
It does appear as a property on the company type. The way to assign a
value to it in the SDO data graph is to have a graph that contains
an employee object through the containment references, and to assign
the object to it. This is illustrated in the later examples below.
a single-valued non-containment reference on the company object, to
which can be assigned references to SDO data objects of the employee
type. It does appear as a property on the company type. The way to
assign a value to it in the SDO data graph is to have a graph that
contains an employee object through the containment references, and to
assign the object to it. This is illustrated in the later examples
below.
</para>
</section>
</section> <!--specifying the metadata -->
@ -1039,7 +1041,8 @@ $das -> applyChanges($dbh, $root);
<para>
Note the way that the company object is actually deleted using the
PHP unset call. The unset has to be performed on the containing
reference which in this case the company reference on the special
reference which in this case is
the company reference on the special
root object. You must use:
<programlisting role="php" id="sdo.das.rel.examples.1cd-CRUD.good-delete">
<![CDATA[
@ -1309,14 +1312,12 @@ echo "Deleted the company, departments and employees all in one go.\n";
<para>
You may be interested in seeing the SQL statements that are generated
in order to apply changes back to the database. At the top of the
<classname>SDO_DAS_Relational</classname>
<filename>SDO/DAS/Relational.php</filename>
you will find a number of constants which control whether the process
of constructing and executing the SQL statements is to be traced.
Try setting
<varname>DEBUG_EXECUTE_PLAN</varname>
to
<varname>true</varname>
to see the generated SQL statements.
to &true; to see the generated SQL statements.
</para>
</section>
@ -1332,7 +1333,7 @@ echo "Deleted the company, departments and employees all in one go.\n";
call to obtain the root object of an empty data graph,
the
<function>executeQuery</function>
call to obtain a data graph continuing data from a relational database,
call to obtain a data graph containing data from a relational database,
and the
<function> applyChanges</function>
call to write changes made to a data graph back to the relational