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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE- 2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<!-- generateKeywords macro -->
<META name="description" content="Apache Tuscany">
<META name="keywords" content="apache, apache tuscany, tuscany, service, services, fabric, soa, service oriented architecture, sca, service component architecture, das, sdo, csa, ruby, opensource">
<!-- generateKeywords macro end -->
<LINK type="text/css" rel="stylesheet" href="http://tuscany.apache.org/stylesheets/default.css">
<LINK rel="SHORTCUT ICON" href="https://cwiki.apache.org/confluence/display/TUSCANY/$images/favicon.ico">
<TITLE>Apache Tuscany : RDB DAS architecture guide</TITLE>
<META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
<BODY onload="init()">
<!-- topNav macro -->
<TABLE valign="top" border="0" cellspacing="0" cellpadding="0" width="100%" background="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg">
<TR>
<TD valing="top" align="left">
<A href="https://cwiki.apache.org/confluence/pages/viewpage.action?spaceKey=TUSCANY&title=$siteroot"><IMG src="http://tuscany.apache.org/images/TuscanyLogoNEW_Text_120px_bg.jpg" height="91" width="25" border="0"></A>
</TD>
<TD>
<A href="http://tuscany.apache.org/"><IMG src="http://tuscany.apache.org/images/TuscanyLogo.jpg" border="0"></A>
</TD>
<TD width="100%">
</TD>
<!-- Adds the edit page link to the top banner-->
<TD valign="bottom">
<DIV style="padding: 2px 10px; margin: 0px;">
<A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=56921">
<IMG src="http://tuscany.apache.org/images/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A>
</DIV>
</TD>
</TR>
</TABLE>
<!-- topNav macro end -->
<!-- breadCrumbs macro -->
<TABLE border="0" cellpadding="2" cellspacing="0" width="100%">
<TR class="topBar">
<TD align="left" valign="middle" class="topBarDiv" nowrap="true" width="100%">
<A href="home.html" title="Apache Tuscany">Apache Tuscany</A> > <A href="home.html" title="Home">Home</A> > <A href="menus.html" title="Menus">Menus</A> > <A href="general.html" title="General">General</A> > <A href="das-general-menu.html" title="DAS General Menu">DAS General Menu</A> > <A href="das-rdb-menu.html" title="DAS RDB Menu">DAS RDB Menu</A> > <A href="" title="RDB DAS architecture guide">RDB DAS architecture guide</A>
</TD>
<TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true">
<A href="http://mail-archives.apache.org/mod_mbox/tuscany-user">User List</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-dev">Dev List</A> | <A href="http://issues.apache.org/jira/browse/Tuscany">Issue Tracker</A>
</TD>
</TR>
</TABLE>
<!-- breadCrumbs macro end -->
<TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF">
<TR>
<TD align="left" valign="top">
<!-- pageContent macro -->
<DIV id="PageContent">
<DIV class="pagecontent">
<DIV class="wiki-content">
<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
<TD class="confluenceTd" valign="top" width="15%">
<DIV class="panel" style="background-color: #ECF4D1;border-color: #C3CDA1;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #C3CDA1;background-color: #C3CDA1;"><B>General</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="home.html" title="Home">Home</A><BR>
<A href="http://www.apache.org/licenses/LICENSE-2.0.html" class="external-link" rel="nofollow">License </A><BR>
<A href="das-java-get-involved.html" title="DAS Java Get Involved">Get Involved</A><BR>
<A href="das-java-found-a-bug.html" title="DAS Java Found A Bug">Found a Bug?</A></P>
</DIV></DIV>
<DIV class="panel" style="background-color: #ECF4D1;border-color: #b4b4b5;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #b4b4b5;background-color: #C3CDA1;"><B>DAS Java</B></DIV><DIV class="panelContent" style="background-color: #ECF4D1;">
<P><A href="das-java.html" title="DAS Java">DAS Java Home</A><BR>
<A href="das-java-faq.html" title="DAS Java - FAQ">FAQ</A><BR>
<A href="das-java-releases.html" title="DAS Java Releases">Downloads</A><BR>
<A href="das-java-documentation-menu.html" title="DAS Java Documentation Menu">Documentation</A><BR>
<A href="https://svn.apache.org/repos/asf/tuscany/java/das/" class="external-link" rel="nofollow">Source Code</A></P>
</DIV></DIV></TD>
<TD class="confluenceTd" valign="top" width="85%">
<DIV class="panel" style="background-color: #ffffff;border-color: #ECF4D1;border-style: solid;border-width: 1px;"><DIV class="panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #ECF4D1;background-color: #ECF4D1;"><B>Apache Tuscany RDB DAS Java Architecture Guide</B></DIV><DIV class="panelContent" style="background-color: #ffffff;">
<UL>
<LI><A href="#RDBDASarchitectureguide-Overview">Overview</A></LI>
<LI><A href="#RDBDASarchitectureguide-FunctionDescription">Function Description</A></LI>
<LI><A href="#RDBDASarchitectureguide-Architecture">Architecture</A></LI>
<LI><A href="#RDBDASarchitectureguide-UserInterface">User Interface</A></LI>
<LI><A href="#RDBDASarchitectureguide-ClassDiagram">Class Diagram</A></LI>
<LI><A href="#RDBDASarchitectureguide-DesignDetails">Design Details</A></LI>
<LI><A href="#RDBDASarchitectureguide-ConfigurationSchema%2528config.xsd%2529">Configuration Schema(config.xsd)</A></LI>
<LI><A href="#RDBDASarchitectureguide-ScalabilityAspects">Scalability Aspects</A></LI>
<LI><A href="#RDBDASarchitectureguide-Future">Future</A></LI>
<LI><A href="#RDBDASarchitectureguide-Samples">Samples</A></LI>
<LI><A href="#RDBDASarchitectureguide-TerminologyandUsefulLinks">Terminology and Useful Links</A></LI>
</UL>
</DIV></DIV>
<H3><A name="RDBDASarchitectureguide-Overview"></A><A name="RDBDASarchitectureguide-Overview"></A>Overview</H3>
<P>Service Data Object (SDO) and Service Component Architecture (SCA) are the basic building blocks in Service Oriented Architecture (SOA). SDO is the way of representing data in SCA. As the applications using SOA have back-end data representation in different formats like Database, File System, XML Based Data, etc., there is a need to provide a mapping between these data representations and SDO. Java RDB DAS (Data Access Service for Relational Database) is the effort to suffice this mapping requirement for Relational Database. There is a C++ implementation coming up too.</P>
<H3><A name="RDBDASarchitectureguide-FunctionDescription"></A><A name="RDBDASarchitectureguide-FunctionDescription"></A> Function Description</H3>
<P>RDB DAS provides 2 major capabilities:-<BR>
1) Execute SQL Queries and return result as a graph of Data Objects.<BR>
2) Reflect changes made to a graph of Data Objects back to the database.<BR>
It also supports explicit CUD SQL statements execution against database.<BR>
<SPAN class="image-wrap" style=""><IMG src="rdb-das-architecture-guide.data/rdbDAS.gif" style="border: 0px solid black"></SPAN></P>
<H3><A name="RDBDASarchitectureguide-Architecture"></A><A name="RDBDASarchitectureguide-Architecture"></A> Architecture</H3>
<P>This section describes the overall architecture of Java RDB DAS. The details are elaborated in <A href="#RDBDASarchitectureguide-DesignDetails">Design Details</A>. Also, for details of different DAS Configuration settings, refer to <A href="#RDBDASarchitectureguide-ConfigurationSchema%2528config.xsd%2529">Configuration Schema(config.xsd)</A>.</P>
<P>DAS functions based on external Configuration. This configuration can be specified using file or can be programmatically build by the caller, using <B>ConfigHelper</B> interface.</P>
<P>Design follows a factory pattern to create DAS instance. DAS instance contains <B>Connection</B>, <B>Config</B> and <B>Commands</B>.</P>
<P>The <B>Connection</B> can either be passed from caller or can be created using the Configuration information. It is used for all the database operations done in that DAS instance and also for controlling transactions. Configuration parameter <B>managedtx</B> decides whether the transaction will be controlled by DAS or by caller.</P>
<P><B>Commands</B> hold all the commands from Configuration file and also the ones that are created programmatically on the fly. The Command is implemented using different inherited classes like <B>Read/Insert/Update/Delete/StoredProcedure/OptimisticWrite</B> with root parent class <B>CommandImpl</B>. More details on different classes will be in <A href="#RDBDASarchitectureguide-DesignDetails">Design Details</A>.</P>
<P><B>Config</B> holds the reference for Configuration associated with the DAS instance and contains all details as mentioned in <A href="#RDBDASarchitectureguide-ConfigurationSchema%2528config.xsd%2529">Configuration Schema (config.xsd)</A>.</P>
<P>Caller has 2 (and some other) main APIs available in DAS instance to use the Commands <B>getCommand(name)</B> and <B>applyChanges(Data Object)</B></P>
<OL>
<LI><B>getCommand(name)</B> is typically used to retrieve the Command (SQL String) available from Config. SQL String, Connection and Parameters required for the SQL are contained in the Command instance. User also needs to call setParameter() on Command as required by the underlying SQL. User finally calls execute() /executeQuery() on this Command and based on whether it is CUD/Read operation. executeQuery() returns DataObject.</LI>
<LI><B>applyChanges(Data Object)</B> is the way to process a SDO DataObject and SDO ChangeSummary to create SQL UPDATE statement to be executed against database. More details on SDO integration are in <A href="#RDBDASarchitectureguide-DesignDetails">Design Details</A>.</LI>
</OL>
<H3><A name="RDBDASarchitectureguide-UserInterface"></A><A name="RDBDASarchitectureguide-UserInterface"></A> User Interface</H3>
<P>DAS exposes a set of interfaces to end user. Javadoc is available for all public APIs in binary distribution from <A href="http://cwiki.apache.org/confluence/display/TUSCANY/DAS%20Downloads" class="external-link" rel="nofollow">Downloads</A>.</P>
<UL>
<LI><B>DASFactory</B> Different options to produce DAS instance using Factory pattern.<BR>
<B>Method Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> DAS </TD>
<TD class="confluenceTd"> createDAS(java.sql.Connection connection) </TD>
<TD class="confluenceTd"> Creates a DAS based on the provided connection </TD>
</TR>
<TR>
<TD class="confluenceTd"> DAS </TD>
<TD class="confluenceTd"> createDAS(java.io.InputStream configStream) </TD>
<TD class="confluenceTd"> Creates a DAS based on the provided config file stream </TD>
</TR>
<TR>
<TD class="confluenceTd"> DAS </TD>
<TD class="confluenceTd"> createDAS(java.io.InputStream configStream, java.sql.Connection connection) </TD>
<TD class="confluenceTd"> Creates a DAS based on the provide config file stream and connection </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<UL>
<LI><B>DAS Interface</B> to call APIs for DAS instance.<BR>
<B>Field Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> static DASFactory </TD>
<TD class="confluenceTd"> FACTORY </TD>
</TR>
</TBODY></TABLE>
</DIV>
<P><B>Method Summary</B></P>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> applyChanges(DataObject root) </TD>
<TD class="confluenceTd"> The change history is scanned and modifications to the graph of data objects are flushed to the database. </TD>
</TR>
<TR>
<TD class="confluenceTd"> Command </TD>
<TD class="confluenceTd"> createCommand(java.lang.String sql) </TD>
<TD class="confluenceTd"> Creates a Command based on the provided SQL statement </TD>
</TR>
<TR>
<TD class="confluenceTd"> Command </TD>
<TD class="confluenceTd"> getCommand(java.lang.String name) </TD>
<TD class="confluenceTd"> Gets the named command from this factory's inventory </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> releaseResources() </TD>
<TD class="confluenceTd"> If the CommandGroup is managing connections then this method must be called when the client is done with the instance. </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<UL>
<LI><B>Command</B> Used to execute read / write (CRUD) on database.<BR>
<B>Method Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> execute() </TD>
<TD class="confluenceTd"> Performs the function defined by the command </TD>
</TR>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> executeQuery() </TD>
<TD class="confluenceTd"> Performs the function defined by the command and return the results in the root DataObject </TD>
</TR>
<TR>
<TD class="confluenceTd"> int </TD>
<TD class="confluenceTd"> getGeneratedKey() </TD>
<TD class="confluenceTd"> Returns the value of the database-generated key. </TD>
</TR>
<TR>
<TD class="confluenceTd"> java.lang.Object </TD>
<TD class="confluenceTd"> getParameter(int index) </TD>
<TD class="confluenceTd"> Returns the value of the associated Parameter </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> setParameter(int index, java.lang.Object value) </TD>
<TD class="confluenceTd"> Sets the value of the associated Parameter </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<UL>
<LI><B>ConfigHelper</B> It is used as an aid in programmatic construction of Config instances. This is an<BR>
alternative to providing needed configuration information in an XML file.<BR>
<B>Constructor Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> ConfigHelper() </TD>
</TR>
<TR>
<TD class="confluenceTd"> ConfigHelper(Config config) </TD>
</TR>
</TBODY></TABLE>
</DIV>
<P><B>Method Summary</B></P>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> Column </TD>
<TD class="confluenceTd"> addColumn(Table table, java.lang.String columnName, java.lang.String propertyName) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addConnectionInfo(java.lang.String dataSourceName) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addConnectionInfo(java.lang.String dataSourceName, boolean managedtx) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addConnectionInfo(java.lang.String driverClass, java.lang.String databaseURL, java.lang.String user, java.lang.String password, int loginTimeout) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addCreateStatement(Table table, java.lang.String statement, java.lang.String parameters) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Command </TD>
<TD class="confluenceTd"> addDeleteCommand(java.lang.String name, java.lang.String sql) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addDeleteStatement(Table table, java.lang.String statement, java.lang.String parameters) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Command </TD>
<TD class="confluenceTd"> addInsertCommand(java.lang.String name, java.lang.String sql) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addPrimaryKey(java.lang.String columnName) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Relationship </TD>
<TD class="confluenceTd"> addRelationship(java.lang.String parentName, java.lang.String childName) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Relationship </TD>
<TD class="confluenceTd"> addRelationship(java.util.Vector parentNames, java.util.Vector childNames) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Command </TD>
<TD class="confluenceTd"> addSelectCommand(java.lang.String name, java.lang.String sql) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Table </TD>
<TD class="confluenceTd"> addTable(java.lang.String name, java.lang.String typeName) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Command </TD>
<TD class="confluenceTd"> addUpdateCommand(java.lang.String name, java.lang.String sql) </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addUpdateStatement(Table table, java.lang.String statement, java.lang.String parameters) </TD>
</TR>
<TR>
<TD class="confluenceTd"> Config </TD>
<TD class="confluenceTd"> getConfig() </TD>
</TR>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> setDataObjectModel(java.lang.String dataObjectModel) </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<UL>
<LI><B>Converter</B> A lightweight Table-column <--> DataObject-property converter framework. Converters allow a user to insert a transformation between a column's value and its destination DataObject property's value. For example, by default, a VARCHAR column will be represented as a String in its corresponding DataObject property. A user could insert a converter that transforms the VARCHAR value to an Integer. If this is done then although the column returns character data, the DataObject property will be an Integer<BR>
<B>Method Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> java.lang.Object </TD>
<TD class="confluenceTd"> getColumnValue(java.lang.Object propertyData) </TD>
<TD class="confluenceTd"> Transform the columnData object to a new value and possibly new type </TD>
</TR>
<TR>
<TD class="confluenceTd"> java.lang.Object </TD>
<TD class="confluenceTd"> getPropertyValue(java.lang.Object columnData) </TD>
<TD class="confluenceTd"> Transform the columnData object to a new value and possibly new type. </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<UL>
<LI><B>Pager</B> An iterator-like interface to conveniently move through chunks of data. The idea is that a Pager works with a read Command. The read command returns a large amount of data and the client wants to work with chunks of it at a time. So the Pager is created on the command and each call to next returns the next chunk of data.<BR>
<B>Method Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> getPage(int page) </TD>
<TD class="confluenceTd"> Return a specific identified page </TD>
</TR>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> next() </TD>
<TD class="confluenceTd"> Get the next page of data </TD>
</TR>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> previous() </TD>
<TD class="confluenceTd"> Get the page prior to the last page returned </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<UL>
<LI><B>GraphMerger</B> is utility class implementation (no interface), to provide functions for flexibly managing DataObjects.<BR>
<B>Constructor Summary</B>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> GraphMerger() </TD>
</TR>
</TBODY></TABLE>
</DIV>
<P><B>Method Summary</B></P>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> void </TD>
<TD class="confluenceTd"> addPrimaryKey(java.lang.String key) </TD>
</TR>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> emptyGraph(Config config) </TD>
</TR>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> merge(DataObject primary, DataObject secondary) </TD>
</TR>
<TR>
<TD class="confluenceTd"> DataObject </TD>
<TD class="confluenceTd"> merge(java.util.List graphs) </TD>
</TR>
</TBODY></TABLE>
</DIV>
</LI>
</UL>
<H3><A name="RDBDASarchitectureguide-ClassDiagram"></A><A name="RDBDASarchitectureguide-ClassDiagram"></A> Class Diagram</H3>
<P><A href="rdb-das-class-diagram.html" title="RDB DAS class diagram">Class Diagram</A></P>
<H3><A name="RDBDASarchitectureguide-DesignDetails"></A><A name="RDBDASarchitectureguide-DesignDetails"></A>Design Details</H3>
<P>Major classes are described here at high level to show how these fit in the complete picture. For <BR>
methods/members details please refer to javadoc from binary distribution at <A href="http://cwiki.apache.org/confluence/display/TUSCANY/DAS%20Downloads" class="external-link" rel="nofollow">Downloads</A>.</P>
<P><B>DASFactoryImpl</B> Expose methods to create DAS instance from Config or Connection or both.</P>
<P><B>DASImpl</B> The sole instance of DAS existing for one DAS runtime. It contains MappingWrapper, JDBC Connection and a Map of all DAS Commands. To create appropriate instances of CommandImpl, DASImpl, scan's each Config Command for attribute kind, and based on that required instance of CommandImpl is added to the map. Connection from DataSource or Database Driver Manager both are supported. releaseResources() method allows external caller to close JDBC Connection when it is supplied by the caller.Provides methods to get/create DAS Commands and applyChanges(changed DataObject) to reflect DataObject changes to Database.</P>
<P><B>MappingWrapper</B> Wrapper over DAS Config. Provides various get/set methods for all different elements in DAS Config.</P>
<P><B>ConnectionImpl</B> Contains JDBC Connection, and whether it is managed by DAS/caller and also whether Database platform support auto-generated key column values.</P>
<P><B>BaseCommandImpl</B> Parent class for all other CommandImpl classes. Contains MappingWrapper. setConnection() method to associate ConnectionImpl with each DAS Command.</P>
<P><B>ApplyChangesCommandImpl</B> Extends BaseCommandImpl. Contains ChangeSummarizer. It is used to load DataObject's ChangeSummary and for each change, Generator classes (UpdateGenerator, DeleteGenerator) are called to form appropriate SQL Statement with parameters, which is executed against the Database.</P>
<P><B>CommandImpl</B> Extends BaseCommandImpl and implements DAS Config's <Command>. So, in effect it is parent class for all explicit CRUD Commands. It contains Statement, Parameters and ResultSetShape.</P>
<P><B>WriteCommandImpl</B> Extends CommandImpl. Parent for CUD. If SELECT(Read) is attempted, exception is thrown.</P>
<P><B>DeleteCommandImpl</B> Extends WriteCommandImpl.</P>
<P><B>InsertCommandImpl</B> Extends WriteCommandImpl. Supports Database generated keys.</P>
<P><B>UpdateCommandImpl</B> Extends WriteCommandImpl.</P>
<P><B>OptimisticWriteCommandImpl</B> Extends UpdateCommandImpl. Supports OCC feature. Here by design when a CollisionParameter's value is attempted to change more than once, the CollisionParameter does not allow its value change (as during first setValue(), flag indicating that value is changed is set). So, the attempt results in no database rows getting changes. On this condition exception is thrown as Update Collision is occurred.</P>
<P><B>ReadCommandImpl</B> Extends CommandImpl. Used for explicit SELECT. Support's DAS feature, ResultDescriptor. If CUD is attempted, exception is thrown. Supports paging. When Query is executed (executeQuery()), the JDBC ResultSet is converted into DataObject Graph and returned to caller.</P>
<P><B>SPCommandImpl</B> Extends ReadCommandImpl for StoredProcedure call. Method executeQuery() is used when the stored procedure returns ResultSet and method execute() is used when the stored procedure does not have any return ResultSet.<BR>
Parameters hold both IN and OUT parameters.</P>
<P><B>PagerImpl</B> Holds ReadCommandImpl, page size and current page index. Implements next(), previous(), getPage(index) methods. In each based on current page index and page size, the ReadCommandImpl is executed with start and end boundaries set.</P>
<P><B>ChangeFactory</B> This class is used during DAS.applyChanges(). With changed DataObject and ChangeSummary, required type of ChangeOperation instance is created (like DeleteOperation, UpdateOperation). This instance of ChangeOperation holds appropriate CommandImpl, which in itself holds the Parameters. Thus for a given DAS Config and Connection, ChangeFactory is used to propagate DataObject changes to Database via CommandImpl.</P>
<P><B>ChangeSummarizer</B> Main function of this class is load Changes based on root DataObject of applyChanges() Command MappingWrapper is used to sort the ChangeOperations in Changes.</P>
<P><B>Changes</B> Contains DeleteList, InsertList, Update List pertaining to one applyChanges() command.</P>
<P><B>DeleteList</B> Maintains ordered/unordered list of DeleteOperations. If DAS Config defines any Relationships, MappingWrapper aids in forming Delete Order for all the Tables undergoing DeleteOperation, based on Parent-Child relationships. If Delete Order is available, DeleteList forms a List following appropriate Referential Integrity. Otherwise no order is maintained.</P>
<P><B>InsertList</B> Maintains ordered/unordered list of CreateOperations. If DAS Config defines any Relationships, MappingWrapper aids in forming Insert Order for all the Tables undergoing InsertOperation, based on Parent-Child relationships. If Insert Order is available, InsertList forms a List following appropriate Referential Integrity. Otherwise no order is maintained.</P>
<P><B>UpdateList</B> As UpdateOperation happens on single Table, there is no reason for sorting based on any Referntial Relationships. So, this class is just a wrapper on ArrayList.</P>
<P><B>BaseGenerator</B> Parent class for Delete/Update/InsertGenerator. If in DAS Config, any Table Column specifies a ColumnConverter class, BaseGenerator, returns a new instance of this class.</P>
<P><B>DeleteGenerator</B> Extends BaseGenerator. Based on Table and DAS Config, DELETE statement is generated with Primary Keys in WHERE clause. Using this, DeleteCommandImpl is instantiated. For Parameters in DeleteCommandImpl ColumnConverter is considered if present.</P>
<P><B>InsertGenerator</B> Same as DeleteGenerator. Here Database Key value generation is also considered.</P>
<P><B>UpdateGenerator</B> Extends BaseGenerator. In UPDATE statement WHERE clause Primary Keys are considered as well as Default OCC policy is considered. Also check is implemented for any violation for Foreign Key relationships. Parameters in UpdateCommandImpl consider ColumnConvert as appropriate. OCC attributes in DAS Config for <Column>, viz. managed and collision are considered in SET and WHERE clause formation respectively.</P>
<P><B>ChangeOperation</B> Abstract parent class for Create/Delete/UpdateOperation. It contains WriteCommand, DatabaseObject and any generated ID.</P>
<P><B>DeleteOperation</B> Extends ChangeOperation. Uses SDO's ChangeSummary based OldValues as in the DataGraph , deleted objects have lost their <B>settings</B>.</P>
<P><B>CreateOperation</B> Extends ChangeOperation, makes use of Generated ID.</P>
<P><B>UpdateOperation</B> Extends ChangeOperation and makes use of generated ID.</P>
<P><B>DatabaseObject</B> Wraps DataObject. If a field is FK, it will return value from parent. It also sets the Database generated value in primary key property of DataObject.</P>
<P><B>RowObjects</B> Holds a Map of TableName->DataObject. It uses relationship information to associate these DataObjects to form DataGraph .</P>
<P><B>GraphBuilderMetadata</B> Class that form Metadata for forming DataObjects based on MetaData available in JDBC ResultSet. It uses DAS Config, ResultSet and ResultSetShape to form a Collection of ResultMetaData. It is used in ResultSetProcessor and thus further in RowObjects.</P>
<P><B>ResultSetProcessor</B> This class is used to transform data in ResultSet into set of inter-related DataObjects. It contains TableRegistry, GraphBuilderMetadata and DataObjectMaker. Using GrapbBuilderMetadata and the JDBC ResultSet, it forms<BR>
ResultSetRow , then form RowObjects and connects related DataObjects using Relationship information from RowObjects to form the completed DataGraph.</P>
<P><B>DataObjectMaker</B> Forms DataObject based on TableData. It is used in ResultSetProcessor for this.</P>
<P><B>TableRegistry</B> Base Interface for Single/MultiTableRegistry.</P>
<P><B>SingleTableRegistry</B> No functionality.</P>
<P><B>MultiTableRegistry</B> Implements TableRegistry. Used when converting JDBC ResultSet of SQL SELECT into DataObjects.</P>
<P><B>DefaultConverter</B> Implements Converter. In case of Blob database column type, returns byte[] for the column value when mapping from database data to property value.</P>
<P><B>ResultMetaData</B> Holds complete ResultSet related metadata of the Query result- ResultSet, ColumnConverters, MappingWrapper, SDO Type Names, SDO Property Names, ResultSetShape for the ResultSet, Map containing Table Type <DEL>> Column Property (equivalent to Database Table</DEL>>Column). It provides various get methods on these members.</P>
<P><B>ResultSetRow</B> A ResultSetRow is used to transform a single row of ResultSet into a set of DataObjects. It uses TableData as a intermediate place to keep Database Data for a Row , which is later used to form DataObject. It holds a List of all Table Data for the current row. This class is used in ResultSetProcessor.</P>
<P><B>TableData</B> Holds single JDBC row for a Table and its Columns - tableName, list of PKs, Map of ColumnName->Data, if table has PK. Is used by DataObjectMaker to form DataObject based on Table Row.</P>
<P><B>ResultSetTypeMap</B> Provides mapping from sql.Types to SDO Type. Used in ResultSetShape to populate SDO Type[] for all columns present in ResultSet.</P>
<P><B>FactoryRegistry</B> Maintains registry of ChangeFactory. There is one FactoryRegistry for on DAS Config and Connection. It maintains a Map with entries of each SDO Type against ChangeFactory for current DAS Config+Connection.</P>
<P><B>ParameterImpl</B> Holds values required for representing SQL statement/StoredProcedure parameter like name, index, value, SDO Type and columnConverter. Can have direction IN/OUT/IN-OUT. IN is default. OUT/IN-OUT is only in case of Stored Procedure.</P>
<P><B>ManagedParameterImpl</B> Extends ParameterImpl. Expected to be integer or BigDecimal type, else exception is thrown. setValue() returns oldValue+1.</P>
<P><B>CollisionParameter</B> Extends ParameterImpl. Design restricts setting value in CollisionParameter only once.</P>
<P><B>Parameters</B> Maintains lists of parameters (used in SQL statements), IN/OUT parameters (used in stored procedures).</P>
<P><B>ResultSetShape</B> This is an alternative to use ResultSetMetaData of the Query result. It can be used when some platforms like Oracle do not fully support MetaData. For a given SQL Query, this holds schemaName, tableName, columnName, SDO Column Type for each column in ResultSet. It has 2 constructors, one uses JDBC's ResultSetMetaData to form ResultSetShape and another uses DAS Config supplied ResultDescriptor to form ResultSetShape.</P>
<P><B>Statement</B> Holds SQL String, JDBC connection, JDBC PreparedStatement and also state information whether the current statement is used by Pager.</P>
<P><B>SDODataTypeHelper</B> Provides mapping between SDO's Type and JDBC's sql.Types.</P>
<P><B>SDODataTypes</B> Uses SDO's TypeHelper to get SDO Type for given string.</P>
<P><B>QualifiedColumn</B> Maintains schemaName, tableName and columnName for a Table's Column.</P>
<P><B>RelationshipWrapper</B> Wrapper for DAS Config's <Relationship>. Only one method to return Collection of all FKColumns in a Relationship.</P>
<P><B>TableWrapper</B> Wrapper on DAS Config's <Table>. Provides various get methods to get values of different elements and attributes within <Table>.</P>
<P><B>ConfigUtil</B> Uses SDO's XMLHelper to load DAS Config Data Model in memory.</P>
<P><B>DataObjectUtil</B> Provides utility methods for SDO DataObject like copying one DataObject into another, restoring Old Values of a DataObject using its SDO's ChangeSummary.</P>
<H3><A name="RDBDASarchitectureguide-ConfigurationSchema%28config.xsd%29"></A><A name="RDBDASarchitectureguide-ConfigurationSchema%28config.xsd%29"></A> Configuration Schema(config.xsd)</H3>
<P>Complete DAS Configuration follows.<BR>
Convention <INS>Element</INS> <attribute> <EM>Child Element</EM></P>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> <INS>Config</INS>-> <BR class="atl-forced-newline">
<uri> Not used <BR class="atl-forced-newline">
<dataObjectModel> Needs a valid value when creating static DataObjects. <BR class="atl-forced-newline">
<databaseSchemaNameSupported> when true, multiple database schema under same database are supported <BR class="atl-forced-newline">
<EM>Command</EM>-0..n <BR class="atl-forced-newline">
<EM>Table</EM>-0..n <BR class="atl-forced-newline">
<EM>Relationship</EM>-0..n <BR class="atl-forced-newline">
<EM>ConnectionInfo</EM>-0..1 <BR class="atl-forced-newline">
<INS>ConnectionInfo</INS>-> <BR class="atl-forced-newline">
<dataSource>complete URL of data source <BR class="atl-forced-newline">
<managedtx>if true, DAS manages database transaction <BR class="atl-forced-newline">
<EM>ConnectionProperties</EM>-0..1 <BR class="atl-forced-newline">
<INS>ConnectionProperties</INS>-> <BR class="atl-forced-newline">
<driverClass>complete qualified class name <BR class="atl-forced-newline">
<databaseURL>database URL <BR class="atl-forced-newline">
<username> authentic database user <BR class="atl-forced-newline">
<password> password for the user <BR class="atl-forced-newline">
<loginTimeout>in milliseconds <BR class="atl-forced-newline">
<INS>Command</INS>-> <BR class="atl-forced-newline">
<name> <BR class="atl-forced-newline">
<SQL kind>Select/Update/Delete/Insert/procedure <BR class="atl-forced-newline">
<EM>Parameter</EM>-0..n <BR class="atl-forced-newline">
<EM>ResultDescriptor</EM>-0..n <BR class="atl-forced-newline">
<INS>Parameter</INS>-> <BR class="atl-forced-newline">
<columnName> database table column name (no meaning when Command kind is procedure) <BR class="atl-forced-newline">
<direction>IN/OUT (OUT makes sense when Command kind is "procedure") <BR class="atl-forced-newline">
<index>used in set/getParameter() on Command based on direction (used when Command kind is procedure). <BR class="atl-forced-newline">
<INS>ResultDescriptor</INS>-> Used as alternative to database result set metadata. <BR class="atl-forced-newline">
<columnName> database table column name <BR class="atl-forced-newline">
<tableName> database table name <BR class="atl-forced-newline">
<schemaName> used when databaseSchemaNameSupported=true <BR class="atl-forced-newline">
<columnType>SDO mapped data type <BR class="atl-forced-newline">
<INS>Relationship</INS>-> <BR class="atl-forced-newline">
<name> <BR class="atl-forced-newline">
<primaryKeyTable> <BR class="atl-forced-newline">
<foreignKeyTable> <BR class="atl-forced-newline">
<many> =true allows for 1:n relationship. If it is false, it's 1:1 relationship. <BR class="atl-forced-newline">
<keyRestricted> In case of 1:1 relationship, if keyRestricted is not specified, the <BR class="atl-forced-newline">
link (relationship) between the parent and child rows can be broken, by setting the <BR class="atl-forced-newline">
parentKeyTable's row to null/deleting the row. Also, a different parent row can <BR class="atl-forced-newline">
be associated to the child row, which has one pre-existing parent row association. <BR class="atl-forced-newline">
If keyRestricted=true, this kind on change in existing relationship is not allowed, <BR class="atl-forced-newline">
user will get exception 'Can not modify a one to one relationship that is key <BR class="atl-forced-newline">
restricted'. <BR class="atl-forced-newline">
<EM>KeyPair</EM>-0..n <BR class="atl-forced-newline">
<INS>KeyPair</INS>-> <BR class="atl-forced-newline">
<PrimaryKeyColumn>database table column name <BR class="atl-forced-newline">
<ForeignKeyColumn>database table column name <BR class="atl-forced-newline">
<INS>Table</INS>-> <BR class="atl-forced-newline">
<tableName>Database table name <BR class="atl-forced-newline">
<typeName>Data Object type name <BR class="atl-forced-newline">
<schemaName> used when databaseSchemaNameSupported=true <BR class="atl-forced-newline">
<EM>Column</EM>-0..n <BR class="atl-forced-newline">
<EM>Create</EM>-0..1 <BR class="atl-forced-newline">
<EM>Update</EM>-0..1 <BR class="atl-forced-newline">
<EM>Delete</EM>-0..1 <BR class="atl-forced-newline">
<INS>Create</INS>-> <BR class="atl-forced-newline">
<sql> INSERT statement in PreparedStement format <BR class="atl-forced-newline">
<parameters>space separated column names used in explicit INSERT <BR class="atl-forced-newline">
<INS>Update</INS>-> <BR class="atl-forced-newline">
<sql> UPDATE statement in PreparedStement format <BR class="atl-forced-newline">
<parameters> space separated column names used in explicit UPDATE <BR class="atl-forced-newline">
<INS>Delete</INS>-> <BR class="atl-forced-newline">
<sql> DELETE statement in PreparedStement format <BR class="atl-forced-newline">
<parameters> space separated column names used in explicit DELETE <BR class="atl-forced-newline">
<INS>Column</INS>-> <BR class="atl-forced-newline">
<columnName> database table column name <BR class="atl-forced-newline">
<propertyName> SDO data object's property name <BR class="atl-forced-newline">
<converterClassName> if converter is used, this needs a valid class name <BR class="atl-forced-newline">
<primaryKey>true if column is PK <BR class="atl-forced-newline">
<generated> true if column value is database generated <BR class="atl-forced-newline">
<collision> when true, during UPDATE statement generation, that column is <BR class="atl-forced-newline">
included in the WHERE clause.(OCC feature) <BR class="atl-forced-newline">
<managed> when true, during UPDATE statement generation, that column (needs <BR class="atl-forced-newline">
to be BigDecimal) value is incremented by 1 and used in the SET clause in <BR class="atl-forced-newline">
UPDATE. <BR class="atl-forced-newline">
managed=true, is effective only when collision=true, else managed attribute value <BR class="atl-forced-newline">
is ignored. </TD>
</TR>
</TBODY></TABLE>
</DIV>
<H3><A name="RDBDASarchitectureguide-ScalabilityAspects"></A><A name="RDBDASarchitectureguide-ScalabilityAspects"></A> Scalability Aspects</H3>
<P>Java RDB DAS has exposed <A href="#RDBDASarchitectureguide-UserInterface">User Interface</A>for end user. Other than that, from design perspective, many major DAS classes do not have associated interfaces and by design are tightly coupled with SDO and Database. It needs further enhancement on this line, especially when more DAS flavors are coming up as mentioned in <A href="#RDBDASarchitectureguide-Future">Future</A>. As DAS is a bridge between SOA based applications and backend Data Sources, the interfaces with SOA and Data Source need to be flexible. E.g. SDO/Some Other mechanism should be pluggable when using DAS as well as different technologies based Data Sources can be supported like XML files, LDAP based file system and so forth. Work is in-progress on this front.</P>
<H3><A name="RDBDASarchitectureguide-Future"></A><A name="RDBDASarchitectureguide-Future"></A> Future</H3>
<P>DAS is implemented in Java and C++ and both are integrated with SDO and support Relational Database based Data Source. There are other flavors of DAS coming up like LDAP DAS, XQuery DAS etc. These implementations will provide different ways to interface with the backend data source as their names suggest.</P>
<H3><A name="RDBDASarchitectureguide-Samples"></A><A name="RDBDASarchitectureguide-Samples"></A> Samples</H3>
<P>There are a couple of samples distributed to demonstrate working examples of using different DAS features. See User Guide/Samples for more details.</P>
<H3><A name="RDBDASarchitectureguide-TerminologyandUsefulLinks"></A><A name="RDBDASarchitectureguide-TerminologyandUsefulLinks"></A> Terminology and Useful Links</H3>
<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TD class="confluenceTd"> 1 </TD>
<TD class="confluenceTd"> User Guide </TD>
<TD class="confluenceTd"> <A href="http://cwiki.apache.org/confluence/display/TUSCANY/RDB%20DAS%20-%20User%20Guide" class="external-link" rel="nofollow">Readme</A> </TD>
</TR>
<TR>
<TD class="confluenceTd"> 2 </TD>
<TD class="confluenceTd"> Getting Started </TD>
<TD class="confluenceTd"> <A href="http://cwiki.apache.org/confluence/display/TUSCANY/Starting%20with%20DAS" class="external-link" rel="nofollow">Readme</A> </TD>
</TR>
<TR>
<TD class="confluenceTd"> 3 </TD>
<TD class="confluenceTd"> All Useful Links </TD>
<TD class="confluenceTd"> <A href="http://cwiki.apache.org/confluence/display/TUSCANY/DAS%20Java" class="external-link" rel="nofollow">Links</A> </TD>
</TR>
</TBODY></TABLE>
</DIV>
</TD></TR></TBODY></TABLE>
</DIV>
</DIV>
</DIV>
<!-- pageContent macro end -->
</TD>
</TR>
</TABLE>
<!-- footer macro -->
<SCRIPT src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</SCRIPT>
<SCRIPT type="text/javascript">
_uacct = "UA-1174707-5";
urchinTracker();
</SCRIPT>
<A href="http://www.statcounter.com/" target="_blank"><IMG src="http://c26.statcounter.com/counter.php?sc_project=2619156&java=0&security=94bd7e7d&invisible=0" alt="website stats" border="0"></A>
<DIV class="footer">
Copyright � 2003-2012, The Apache Software Foundation </BR>
Apache Tuscany and the Apache Tuscany project logo are trademarks of The Apache Software Foundation.
</DIV>
<!-- footer macro end -->
</BODY>
</HTML>
|
