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
153
154
155
156
157
158
159
160
161
162
163
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.4 $ -->
<!-- Purpose: database.abstract -->
<!-- Membership: pecl -->
<!-- State: experimental -->
<book xml:id="book.sdodasrel" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>SDO Relational Data Access Service</title>
<titleabbrev>SDO-DAS-Relational</titleabbrev>
<!-- {{{ preface -->
<preface xml:id="intro.sdodasrel">
&reftitle.intro;
<para>
<!-- This warns that the extension is experimental -->
&warn.experimental;
</para>
<para>
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,
the change summary, XPath and property expressions, and so on.
If you are not familiar with these ideas, you might want to look first at
<link linkend='ref.sdo'>the section on SDO</link>.
In addition, the Relational DAS makes use of the PDO extension to
isolate itself from specifics of different back-end relational databases.
In order to use the Relational DAS you will need to be able to
create and pass a PDO database connection;
for this reason you might also want to take a look at
<link linkend="intro.pdo">the section on PDO</link>.
</para>
<para>
The job of the Relational DAS is to move data between the application
and a relational database. In order to do this it needs to be told
the mapping between the database entities
- tables, columns, primary keys and foreign keys -
and the elements of the SDO model
- types, properties, containment relationships and so on.
You specify this information as metadata when you
construct the Relational DAS.
</para>
<procedure xml:id='overview'>
<title>Overview of Operation</title>
<step>
<para>
The first step is to call the Relational DAS's constructor,
passing the metadata that defines the mapping between
database and SDO model.
There are examples of this below.
</para>
</step>
<step>
<para>
The next step might be to call the
<function>executeQuery</function>
or
<function>executePreparedQuery</function>
methods on the Relational DAS, passing either a literal SQL statement
for the DAS to prepare and execute, or a prepared statement with
placeholders and a list of values to be inserted.
You may also need to specify a small amount of metadata
about the query itself, so that the Relational DAS knows
exactly what columns will be returned from the database and
in what order. You will also need to pass a PDO database connection.
</para>
<para>
The return value from
<function>executeQuery</function>
or
<function>executePreparedQuery</function>
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 SDO containment relationships.
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 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>
<step>
<para>
Quite possibly the data in the data graph will go through
a number of modifications. The data graph can be serialised
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 data objects in the graph can be modified.
</para>
</step>
<step>
<para>
Finally, the changes made to the data graph can be applied
back to the database using the
<function>applyChanges</function>
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.
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. 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
committed to the database. The application can then continue to work
with the data graph, make more changes and apply them, or can discard
it.
</para>
</step>
</procedure>
<para>
There are other ways of working with the data in the database:
it is possible to just create data objects and write them to the
database without a preliminary call to
<function>executeQuery</function>,
for example. This scenario and others are explored in the
<link linkend="sdo.das.rel.examples">Examples</link>
section below.
</para>
</preface>
<!-- }}} -->
&reference.sdodasrel.setup;
&reference.sdodasrel.constants;
&reference.sdodasrel.examples;
&reference.sdodasrel.limitations;
&reference.sdodasrel.reference;
</book>
<!-- 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
-->
|
