1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<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>SDODataObject</type>
<parameter>root_data_object</parameter>
</methodparam>
</methodsynopsis>
&warn.experimental.func;
<para>
Given a PDO database handle and the special root object of a data graph,
examine 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="errors">
&reftitle.errors;
<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
-->
|
