From 88cb6dc07c5caa2cdf477dc8a91b3ab793fbce7f Mon Sep 17 00:00:00 2001 From: Matthew Peters Date: Tue, 26 Jul 2005 14:02:08 +0000 Subject: [PATCH] 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 --- reference/sdodasrel/reference.xml | 77 ++++++++++++++++--------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/reference/sdodasrel/reference.xml b/reference/sdodasrel/reference.xml index b9ab95a20e..0253e571ae 100644 --- a/reference/sdodasrel/reference.xml +++ b/reference/sdodasrel/reference.xml @@ -1,5 +1,5 @@ - + SDO Relational Data Access Service Functions @@ -13,7 +13,7 @@ &warn.experimental; - 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. 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. @@ -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. @@ -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 applyChanges. 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'; 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. @@ -326,7 +326,7 @@ require_once 'SDO/DAS/Relational.php'; FK 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); There are a few simple rules to be followed when constructing the - database metadata + database metadata: - 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. @@ -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. @@ -568,13 +569,12 @@ $SDO_reference_metadata = array($department_reference, $employee_reference); dept_id 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 co_id 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); The third foreign key in this example, the employee_of_the_month + , 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. @@ -1039,7 +1041,8 @@ $das -> applyChanges($dbh, $root); 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: 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 - SDO_DAS_Relational + SDO/DAS/Relational.php 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 DEBUG_EXECUTE_PLAN - to - true - to see the generated SQL statements. + to &true; to see the generated SQL statements. @@ -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 executeQuery - 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 applyChanges call to write changes made to a data graph back to the relational