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
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
|
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Java SDO Overview</title>
<bannertitle>Java SDO Overview</bannertitle>
<author email="kelvingoodson+tuscanysite@gmail.com">Kelvin Goodson</author>
<tab>sdo</tab>
</properties>
<body>
<section name="Tuscany Service Data Objects - Java">
<H2>The Tuscany SDO Java Project</H2>
<P>This document proves a high-level overview of the Java SDO (Service
Data Objects) subproject of the Apache Tuscany incubator project.</P>
</section>
<section name="SDO Java Getting Started">
<p>
To get started with Java SDO, follow the downloads link and pick up either a binary or source distribution. If you
are working from a source distribution, you can follow the <a href="java-projects.html">general instructions</a> for building the whole of the Tuscany java projects, or you
can follow the intructions within the <A href="java_sdo_overview.html"> SDO Java overview </A> to build and explore just SDO java.
</p>
<h3>SDO Java Documents</h3>
<table>
<tr>
<td>
<a href="http://www.osoa.org/download/attachments/36/Java-SDO-Spec-v2.1.0-FINAL.pdf?version=1"> SDO Specification for Java V2.01</a>
</td>
<td>
The Service Data Objects specification for Java. Describes the data programming interfaces of SDO in the Java language.
</td>
</tr>
<tr>
<td><a href="http://www.osoa.org/download/attachments/287/Next-Gen-Data-Programming-Whitepaper.pdf?version=1">SDO White Paper</a></td>
<td>A white paper that explains the SDO programming model</td>
</tr>
</table>
</section>
<section name="SDO Java Overview">
<P>The SDO Java project is a subproject of <A class="external"
rel="nofollow" href="http://incubator.apache.org/tuscany/"> the Apache Tuscany incubator project</A>
is intended to provide a Java implementation of the <A class="external"
rel="nofollow"
href="http://www.osoa.org/download/attachments/36/Java-SDO-Spec-v2.1.0-FINAL.pdf?version=1"> SDO 2 specification.</A></P>
<P>The project's code base includes the following:</P>
<UL>
<LI>
<P>Dynamic data object support</P>
</LI>
<LI>
<P>Basic static code generation (generator patterns still subject to
change)</P>
</LI>
<LI>
<P>Most Helper classes either partially or fully implemented
(XMLHelper, XSDHelper, DataFactory, CopyHelper, EqualityHelper)</P>
</LI>
<LI>
<P>Minimal ChangeSummary support (only in DataGraph context)</P>
</LI>
<LI>
<P>Limited example programs</P>
</LI>
</UL>
<P>The Tuscany wiki contains an area for <A class="external" rel="nofollow"
href="http://wiki.apache.org/ws/Tuscany/TuscanyJava/SDO/ThinkingAloud/"> raw thoughts and clarifications on SDO</A> that
will eventually make it into well crafted documentation.</P>
<H3>Build Environment
Setup</H3>
<H4 id="head-c3468f5a294e14dda4ae0cf21a4acf497a9b9e80">Tuscany Build
Environment Setup</H4>
<P>SDO 2 is a subproject of the Tuscany project. If you check out and
build the whole Tuscany Java project, you will have also built the SDO 2
subproject. If you want to work with the SDO 2 project, without the rest
of Tuscany, skip to the next section.</P>
<P>To build the whole Tuscany project follow <A class="external"
rel="nofollow"
href="java-projects.html"> these instructions</A>.</P>
<H4 >SDO Java Build
Environment Setup</H4>
<P>There are two motivations for building SDO from source and two well tested approches to doing so.
You may be wanting to build a binary release distribution from source code. Alternatively you may be
wishing to establish a development environment in order to futher the development of the code. The two
tested approaches are either to use maven 2 commandline builds or to java source code create projects
in the Eclipse SDK.
</P>
<P>If you simply want to create a source code distribution, then even if you are an Eclipse user
its best to just follow the instructions in the BUILDING.txt file at the top of the source code distribution
and run a maven command line build (since the route to establishing an Eclipse environment requires installing maven anyway).
Note that SDO for Java is distributed as two source code distributions. You'll need to
<A HREF="downloads.html">download</A>
two archives, one for the SDO API, and one for the Tuscany implementation of that API.
</P>
<P>If you want to work with the SDO projects alone, without the rest of
Tuscany, proceed with the following steps.</P>
<OL type="1">
<LI>
<P>Set up your environment using the <A class="external" rel="nofollow"
href="java-projects.html"> instructions for building the whole of Tuscany</A>,
<STRONG>but</STRONG> only download and install Java 5, Maven and Svn
(note that only one file, Interface2JavaGenerator.java, has a Java 5
dependency, if you want to work with Java 1.4.2 then just delete this
file before building).</P>
</LI>
<LI>
<P>Make sure 'mvn' and 'svn' commands are in your PATH environment
variable.</P>
</LI>
<LI>
<P>Check out the SDO open source projects from Apache.</P>
</LI>
<UL>
<LI style="list-style-type: none;">
<P>Commands:</P>
<P>md <local tuscany dir> <BR/>
cd <local tuscany dir> <BR/>
svn co -N <A rel="nofollow"
href="https://svn.apache.org/repos/asf/incubator/tuscany/java">
https://svn.apache.org/repos/asf/incubator/tuscany/java</A> <BR/>
cd java <BR/>
svn up sdo <BR/>
svn up -N spec <BR/>
cd spec <BR/>
svn up sdo-api <BR/>
</P>
</LI>
</UL>
</OL>
<OL start="4" type="1">
<LI>
<P>Run "mvn" under <local tuscany dir>/java directory to install
POM files from the root project to the local repository</P>
</LI>
</OL>
<UL>
<LI style="list-style-type: none;">
<P>Commands:</P>
<UL>
<LI style="list-style-type: none;">
<P>cd <local tuscany dir>/java <BR/>
mvn -N <BR/>
cd spec <BR/>
mvn -N <BR/>
cd ../sdo <BR/>
mvn -N (alternatively, run without the -N option - see Note below) <BR/>
</P>
</LI>
</UL>
</LI>
</UL>
<OL start="5" type="1">
<LI>
<P>Build, or rebuild, the individual SDO projects</P>
<UL>
<LI style="list-style-type: none;">
<P><STRONG>sdo.spec</STRONG> project</P>
<P>Commands:</P>
<UL>
<LI style="list-style-type: none;">
<P>cd <local tuscany dir>/java/spec/sdo-api <BR/>
mvn <BR/>
mvn -Peclipse eclipse:eclipse (optional: Run this command if you are using
Eclipse for development.) <BR/>
</P>
</LI>
</UL>
<P><STRONG>sdo.impl</STRONG> project</P>
<P>Commands:</P>
<UL>
<LI style="list-style-type: none;">
<P>cd <local tuscany dir>/java/sdo/impl <BR/>
mvn <BR/>
mvn -Peclipse eclipse:eclipse (optional: Run this command if you are using
Eclipse for development.) <BR/>
</P>
</LI>
</UL>
<P><STRONG>sdo.tools</STRONG> project</P>
<P>Commands:</P>
<UL>
<LI style="list-style-type: none;">
<P>cd <local tuscany dir>/java/sdo/tools <BR/>
mvn <BR/>
mvn -Peclipse eclipse:eclipse (optional: Run this command if you are using
Eclipse for development.) <BR/>
</P>
</LI>
</UL>
<P><STRONG>sdo.samples</STRONG> project</P>
<P>Commands:</P>
<UL>
<LI style="list-style-type: none;">
<P>cd <local tuscany dir>/java/sdo/sample <BR/>
mvn <BR/>
mvn -Peclipse eclipse:eclipse (optional: Run this command if you are using
Eclipse for development.) <BR/>
</P>
</LI>
</UL>
</LI>
</UL>
</LI>
</OL>
<UL>
<LI style="list-style-type: none;">
<P><STRONG>Notes:</STRONG></P>
<OL type="1">
<LI>
<P>You can all of the sdo.impl, sdo.tools and sdo.sample projects in one step by running
mvn in <local tuscany dir>/java/sdo.</P>
</LI>
<LI>
<P>If the mvn command completed successfully, you will see BUILD
SUCCESSFUL in the output and the results of compilation will be available in jar files created under
directories named "target" directly under the root directories of the projects. These jar files are also
installed into your local maven repository ($HOME/.m2/repository) and are available as inputs to later build
operations.</P>
</LI>
<LI>
<P>Maven fetches external resources required for a build process from the internet.
These resources are at times unavailable. It may be necessary to
run "mvn" again at a later time.</P>
</LI>
<LI>
<P>If you are taking time to reply to firewall prompts, this can cause
some requests to time out. Set up the firewall to permit the action
without prompting.</P>
</LI>
</OL>
</LI>
</UL>
<H3 >SDO Project
Structure</H3>
<P>The SDO project is divided into five parts:</P>
<OL type="1">
<LI>
<P><STRONG>sdo.spec</STRONG> contains the SDO (commonj) interfaces
defined and provided by the SDO 2 specification.</P>
</LI>
<LI>
<P><STRONG>sdo.impl</STRONG> provides the runtime implementation of the
SDO interfaces.</P>
</LI>
<LI>
<P><STRONG>sdo.tools</STRONG> contains import and generator tools.</P>
</LI>
<LI>
<P><STRONG>sdo.sample</STRONG> contains sample sdo code.</P>
</LI>
<LI>
<P><STRONG>sdo.plugin</STRONG> contains code to configure the way in which SDO is build by maven.</P>
</LI>
</OL>
<P>The main source code in each of these subprojects is located in the
directory src/main/java, and if applicable, test (example) classes are
located in src/test/java. The directory src/test/resources contains any
data files needed by the test programs.</P>
<H4 >sdo.spec</H4>
<P>(<A rel="nofollow"
href="https://svn.apache.org/repos/asf/incubator/tuscany/java/spec/sdo-api">
https://svn.apache.org/repos/asf/incubator/tuscany/java/spec/sdo-api</A>)</P>
<P>This project contains the interfaces provided with the SDO 2
specification. It is essentially an unzipped copy of the SDO Java API
sources zip file available at <A rel="nofollow"
href="http://ftpna2.bea.com/pub/downloads/SDO_20_Source.zip">
http://ftpna2.bea.com/pub/downloads/SDO_20_Source.zip</A>, but with some
errata corrections and a Tuscany-specific implementation of class
HelperProvider.</P>
<P>The abstract class, HelperProvider, is used to obtain specific
default helpers and other implementation-specific objects used by the
Java implementation of SDO. In the Tuscany implementation of this class,
there are two ways to specify the implementation of the HelperProvider
class.</P>
<OL type="1">
<LI>
<P>Set a System Property named "commonj.sdo.impl.HelperProvider" equal
to the fully qualified class name of the implementation class (e.g.
"commonj.sdo.impl.HelperProvider=org.apache.tuscany.sdo.help.HelperProviderImpl").
</P>
</LI>
<LI class="gap">
<P>In your own jar file, create a text file called
"META-INF/services/commonj.sdo.impl.HelperProvider". In this text file,
specify the fully qualified custom HelperProvider implementation class
(e.g. org.apache.tuscany.sdo.help.HelperProviderImpl).</P>
</LI>
</OL>
<P>In the event that both 1 and 2 are specified, the System Property
will take precedence over the text file.</P>
<P>The Tuscany default helper provider implementation class is
org.apache.tuscany.sdo.helper.HelperProviderImpl (in the sdo.impl
project) and is registered using the second technique (services file),
as described in the following section.</P>
<H4 >sdo.impl</H4>
<P>(<A rel="nofollow"
href="https://svn.apache.org/repos/asf/incubator/tuscany/java/sdo/impl">
https://svn.apache.org/repos/asf/incubator/tuscany/java/sdo/impl</A>)</P>
<P>The sdo.impl subproject contains a test package under src/test/java
(see the section below entitled <A
href="#generator">Static
Code Generator</A> for details) and the following implementation
packages under src/main/java:</P>
<P>package <EM>org.apache.tuscany.sdo</EM></P>
<UL>
<LI style="list-style-type: none;">
<P>Contains a few interfaces used by some of the implementation classes
in org.apache.tuscany.sdo.impl. (Note: this package is subject to
further cleanup.)</P>
</LI>
</UL>
<P>package <EM>org.apache.tuscany.sdo.helper</EM></P>
<UL>
<LI style="list-style-type: none;">
<P>This package contains implementations of the "helper" interfaces
defined in the commonj.sdo.helper package (in the sdo.spec project).
Each helper interface in commonj.sdo.helper has a corresponding
implementation class in this package. The name of each helper class is
the same as the corresponding interface, only with the suffix "Impl"
appended. For example class
org.apache.tuscany.sdo.helper.TypeHelperImpl implements the interface
commonj.sdo.TypeHelper.</P>
<P>The implementation class
org.apache.tuscany.sdo.helper.HelperProviderImpl is used to bootstrap
an implementation of the default INSTANCEs of the SDO helper (see class
commonj.sdo.impl.HelperProvider in sdo.spec). This implementation
creates instances of the other helper implementation classes in this
package and is registered using the services file
src/main/resources/META-INF/services/commonj.sdo.impl.HelperProvider.</P>
</LI>
</UL>
<P>package <EM>org.apache.tuscany.sdo.impl</EM></P>
<UL>
<LI style="list-style-type: none;">
<P>This package contains the majority of the SDO runtime implementation
code. This includes implementations of all of the commonj.sdo
interfaces (see sdo.spec), including several implementations of the
DataObject interface. The design and implementation of the most
important classes in this package are described <A
href="#runtime">below</A>).
</P>
</LI>
</UL>
<P>package <EM>org.apache.tuscany.sdo.util</EM></P>
<UL>
<LI style="list-style-type: none;">
<P>Contains some utility classes used by the implementation. One class,
SDOUtil, is particularly important. It provides some useful static
utility functions which are not included in the SDO specification
itself. Although these are not "standard" APIs, use of them is
recommended, as opposed to resorting to low-level
implementation-specific APIs. The intent of this class is to
encapsulate, in a relatively clean way, common functions that are
needed, and can potentially be proposed for addition to the
specification in a future version of SDO.</P>
</LI>
</UL>
<H4 >sdo.tools</H4>
<P>This project will contain (command line) tools, such as SDO model
importers and generators (Java code, XML schema, etc.). Currently
however, there is only a single tool, a Java code generator implemented
in class org.apache.tuscany.sdo.generate.XSD2JavaGenerator. This
generator can be used to generate static SDO data objects and is
described in more detail in <A
href="#generator">below</A>.
</P>
<P>The sdo.tools project also contains a test program and sample
generated model located in src/test/java and src/test/resources
respectively (see the <A
href="#tests">tests</A>
section below for more details).</P>
<H3 >Dependency Jars</H3>
<P>The sdo.impl project requires the following EMF (Eclipse Modeling
Framework - www.eclipse.org/emf) runtime jars to build:</P>
<UL>
<LI>
<P>emf-common-2.2.1-SNAPSHOT.jar - some common framework utility and
base classes</P>
</LI>
<LI>
<P>emf-ecore-2.2.1-SNAPSHOT.jar - the EMF core runtime implementation
classes (the Ecore metamodel)</P>
</LI>
<LI>
<P>emf-ecore-change-2.2.1-SNAPSHOT.jar - the EMF change recorder and
framework</P>
</LI>
<LI>
<P>emf-ecore-xmi-2.2.1-SNAPSHOT.jar - EMF's default XML (and XMI)
serializer and loader</P>
</LI>
<LI>
<P>xsd-2.2.1-SNAPSHOT.jar - the XML Schema model</P>
</LI>
</UL>
<P>The sdo.tools project also requires the EMF code generator framework
jars:</P>
<UL>
<LI>
<P>emf-codegen-2.2.1-SNAPSHOT.jar - template-based codegen framework
(JET - Java Emitter Templates)</P>
</LI>
<LI>
<P>emf-codegen-ecore-2.2.1-SNAPSHOT.jar - the EMF code generator</P>
</LI>
<LI>
<P>emf-common-2.2.1-SNAPSHOT.jar - some common framework utility and
base classes</P>
</LI>
<LI>
<P>emf-ecore-2.2.1-SNAPSHOT.jar - the EMF core runtime implementation
classes (the Ecore metamodel)</P>
</LI>
<LI>
<P>emf-ecore-change-2.2.1-SNAPSHOT.jar - the EMF change recorder and
framework</P>
</LI>
<LI>
<P>emf-ecore-xmi-2.2.1-SNAPSHOT.jar - EMF's default XML (and XMI)
serializer and loader</P>
</LI>
<LI>
<P>xsd-2.2.1-SNAPSHOT.jar - the XML Schema model</P>
</LI>
</UL>
<P>These are simply Maven-friendly versions of corresponding jar
files/plugins obtained from Eclipse. SNAPSHOT maps to an EMF weekly
integration build (for example, I200602160000). Note that if you are building
SDO for a released source code distribution then the dependency jars will not be
snapshot jars, but will instead themselves be released versions of the dependencies.</P>
<A id="runtime"></A>
<P></P>
<H3 >Runtime
Implementation</H3>
<P>The primary SDO runtime implementation classes are located in the
package org.apache.tuscany.sdo.impl and consist of the following:</P>
<OL type="1">
<LI>
<P>DataObject implementation classes</P>
</LI>
<LI>
<P>Implementation of the SDO metamodel interfaces: Type and Property</P>
</LI>
<LI>
<P>ChangeSummary and DataGraph implementations</P>
</LI>
</OL>
<P>The implementation of the SDO runtime is based on and leverages the
EMF runtime model (i.e., EObject and the Ecore metamodel - refer to
documentation at www.eclipse.org/emf). It subclasses and specializes the
Ecore metamodel, and provides its own DataObject-tuned implementation(s)
of the EObject interface. The design is described in more detail in the
following sections.</P>
<H4 >DataObject
implementation classes</H4>
<P>SDO provides several DataObject implementation classes as shown in
the following diagram:</P>
<P><img src="./images/do_uml.png" alt="do_uml.png" /></P>
<P>Class DataObjectImpl is the most important. It provides a complete
base implementation of the SDO DataObject interface. It extends from the
EMF base class BasicEObjectImpl, which provides the "scaffolding" needed
to easily implement an EObject, but without allocating any storage
itself.</P>
<P>DataObjectImpl provides the DataObject implementation while
allocating only the minimum storage overhead needed to be a data object
(e.g., container pointer and feature, change recorder). It does not,
however, allocate any storage for the actual properties of the data
object. It instead requires subclasses for this purpose. For example,
statically generated SDOs (see the <A
href="#generator">generator</A>
section below) directly or indirectly extend from this class, providing
their own storage in generated instance variables.</P>
<P>The subclass, DynamicDataObjectImpl serves as a concrete
implementation class for dynamic data objects. It is the default
implementation class used when creating dynamic data objects using the
DataFactory.create() method, for example. DynamicDataObjectImpl provides
efficient data storage using a dynamically allocated settings array.</P>
<P>StoreDataObjectImpl and DynamicStoreDataObjectImpl provide a
delegating implementations for DataObjects that implement their own
storage management using a store (see EMF's EStore interface)
implementation class. StoreDataObjectImpl is used in conjuction with the
"-storePattern" generator option (see section 4), while
DynamicStoreDataObjectImpl, as its name implies, is used for dynamic
store-based instances.</P>
<H4 >Type and Property
implementation classes</H4>
<P>The SDO implementation provides three implementations of the
interface Type, one for each of the following three kinds of types:
classes, simple data types, and enumerations.</P>
<OL type="1">
<LI>
<P>class ClassImpl extends EClassImpl implements Type</P>
</LI>
<LI>
<P>class DataTypeImpl extends EDataTypeImpl implements Type</P>
</LI>
<LI>
<P>class EnumImpl extends EEnumImpl implements Type</P>
</LI>
</OL>
<P>For example, class org.apache.tuscany.sdo.impl.ClassImpl extends form
the corresponding Ecore class, EClassImpl, and mixes in the SDO
interface commonj.sdo.Type. All the Type methods are implemented by
calls to super.</P>
<P>With this approach, a data object's Type, returned from
DataObjectImpl.getType(), and its EClass, returned by
DataObjectImpl.eClass(), are the same underlying meta object. This
allows the SDO implementation to leverage any appropriate base
functionality without any performance overhead. The arrangement is shown
in the following diagram:</P>
<P><IMG src="./images/meta.png" alt="meta.png" /></P>
<P>The implementation of the SDO Property interface follows a similar
pattern. Two implementation classes, subclasses of corresponding Ecore
classes, mix in the Property interface:</P>
<OL type="1">
<LI>
<P>class AttributeImpl extends EAttributeImpl implements Property</P>
</LI>
<LI>
<P>class ReferenceImpl extends EReferenceImpl implements Property</P>
</LI>
</OL>
<P>As with the Type implementation classes, these classes call methods
on super to implement the mixed-in Property methods.</P>
<P>The following diagram illustrates the design:</P>
<P><IMG
src="./images/meta2.png"
alt="meta2.png" /></P>
<P>As shown, the getProperties() method in ClassImpl (i.e., of the SDO
Type interface) returns a set of properties whose implementation classes
also implement EAttribute or EReference, and since ClassImpl, extends
EClassImpl (as shown in the previous diagram), these are in fact the
same objects as those returned by the EClass.getEAllStructuralFeatures()
method. The two metamodels are one and the same, making the
implementation of many of the SDO APIs trivial calls to the base class.
</P>
<H4 >ChangeSummary and
DataGraph implementation classes</H4>
<P>TBD.</P>
<A id="generator"></A>
<P></P>
<H2 >Static Code
Generator</H2>
<P>The SDO static code generator is a command line tool for generating
Java source code (static SDOs) for DataObjects defined in an XML Schema.
It is implemented by the class
org.apache.tuscany.sdo.generate.XSD2JavaGenerator in the sdo.tools
project. The generator is used as follows:</P>
<P>Usage arguments:</P>
<PRE> [ -targetDirectory <target-root-directory> ]
[ -javaPackage <base-package-name> ]
[ -prefix <prefix-string> ]
[ -sparsePattern | -storePattern ]
[ -noInterfaces ] [ -noContainment ] [ -noNotification ] [ -arrayAccessors ] [ -noUnsettable ] [-noEMF]
<xsd-file> | <wsdl-file>
</PRE>
<P>For example:</P>
<P>java XSD2JavaGenerator somedir/somefile.xsd</P>
<P>Options:</P>
<UL>
<LI style="list-style-type: none;">
<P><STRONG>-targetDirectory</STRONG> Generates the Java source code in
the specified directory. By default, the code is generated in the same
directory as the input xsd or wsdl file.</P>
<P><STRONG>-javaPackage</STRONG> Overrides the Java package for the
generated classes. If not specified, a default package or one specified
with an sdoJava:package annotation on the <schema> element in the
xsd file (see SDO specification for details) is used for the java
package.</P>
<P><STRONG>-prefix</STRONG> Specifies the prefix string to use for
naming the generated factory. For example "-prefix Foo" will result in
a factory interface with the name "FooFactory".</P>
<P><STRONG>-sparsePattern</STRONG> For SDO metamodels that have classes
with many properties of which only a few are typically set at runtime,
this option can be used to produce a space-optimized implementation (at
the expense of speed).</P>
<P><STRONG>-storePattern</STRONG> This option can be used to generate
static classes that work with a Store-based DataObject implementation.
It changes the generator pattern to generate accessors which delegate
to the reflective methods (as opposed to the other way around) and
changes the DataObject base class to
org.apache.tuscany.sdo.impl.StoreDataObjectImpl. Note that this option
generates classes that require a Store implementation to be provided
before they can be run.</P>
<P><STRONG>-noInterfaces</STRONG> By default, each DataObject generates
both a Java interface and a corresponding implementation class. If an
SDO metamodel does not use multiple inheritance (which is always the
case for XML Schema derived models), then this option can be used to
eliminate the interface and to generate only an implementation class.</P>
<P><STRONG>-noNotification</STRONG> This option eliminates all change
notification overhead in the generated classes. Changes to DataObjects
generated using this option cannot be recorded, and consequently the
classes cannot be used with an SDO ChangeSummary or DataGraph.</P>
<P><STRONG>-noContainment</STRONG> Turns off container management for
containment properties. DataObject.getContainer() will always return
null for data objects generated with this option, even if a containment
reference is set. Setting a containment reference will also not
automatically remove the target object from its previous container, if
it had one, so it will need to be explicitly removed by the client. Use
of this option is only recommended for scenarios where this kind of
container movement/management is not necessary.</P>
<P><STRONG>-arrayAccessors</STRONG> Generates Java array
getters/setters for multiplicity-many properties. <STRONG>Note that
this option is experimental prototype code and is not fully developed
</STRONG>With this option, the
set of "standard" JavaBean array accessor methods (e.g., Foo[]
getFoo(), Foo getFoo(int), int getFooLength(), setFoo(Foo[]), and void
setFoo(int, Foo)) are generated. The normal List-returning accessor is
renamed with the suffix "List" (e.g., List getFooList()). The array
returned by the generated method is not a copy, but instead a pointer
to the underlying storage array, so directly modifying it can have
undesirable consequences and should be avoided.</P>
<P><STRONG>-noUnsettable</STRONG> By default, some XML constructs
result in SDO property implementations that maintain additional state
information to record when the property has been set to the "default
value", as opposed to being truly unset (see DataObject.isSet() and
DataObject.unset()). The SDO specification allows an implementation to
choose to provide this behavior or not. With this option, all generated
properties will not record their unset state. The generated isSet()
methods simply returns whether the current value is equal to the
property's "default value".</P>
<P><STRONG>-noEMF</STRONG> By default, the generated java
implementation source files directly import the Eclipse EMF classes
which they depend upon. This can lead to a discrepancy in EMF library
level dependencies between the generated classes and the environment
into which they are deployed. The -noEmf option provides an early level
of function to avoid this situation. Classes generated using this
option access EMF function indirectly via inherited behaviour, thereby
allowing packaging of these generated classes into jar files which do
not directly depend on EMF.</P>
<P>This early implementation of this option is limited in the subset of
XML Schema it is known to handle, and is subject to change. The
generator is known to be able to deal with Complex content (including
content models which map to SDO Sequence), and Mixed content for
example .</P>
<PRE> <xsd:complexType mixed="true" name="Sequence">
<xsd:sequence>
<xsd:choice maxOccurs="unbounded" minOccurs="0">
<xsd:element name="a" type="xsd:string" />
<xsd:element name="b" type="xsd:int" />
</xsd:choice>
<xsd:element name="split" type="xsd:string" />
<xsd:choice maxOccurs="unbounded" minOccurs="0">
<xsd:element name="y" type="xsd:string" />
<xsd:element name="z" type="xsd:int" />
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
</PRE></LI>
</UL>
<H4 >Generator
Patterns</H4>
<P>The DataObject interface generation pattern is as described in the
SDO specification (see Java Interface Specification section). The SDO
specification does not define a factory pattern for efficient
construction of static SDOs, which is however provided by the Tuscany
implementation. The generated SDO Factory interface conforms to the
following pattern:</P>
<PRE>public interface <prefix>Factory {
<Type1> create<Type1>();
<Type2> create<Type2>();
...
<prefix>Factory INSTANCE = <default_factory_impl>;
}
</PRE>
<P>A generated factory corresponds to an SDO Type namespace uri (see
commonj.sdo.Type.getURI) with one create() method for each SDO Type in
the namespace. The <prefix> of the factory name is derived from
the uri. An instance of the factory is available using the INSTANCE
field in the interface.</P>
<P>Using the static factory, a DataObject might be created as follows:</P>
<PRE>Quote aQuote = StockFactory.INSTANCE.createQuote();
... // do something with aQuote
</PRE>
<P>The generated implementation of each create() method simply
constructs an instance of the corresponding type like this:</P>
<PRE> public Quote createQuote() {
QuoteImpl quote = new QuoteImpl();
return quote;
}
</PRE>
<P>In addition to these generated type-specific create<Type>()
methods, the generated factory implementation class also includes a
generated reflective create() method that, given an SDO Type,
efficiently dispatches to the correct type-specific create() method. The
reflective create() method is called by the implementation of the SDO
commonj.sdo.helper.DataFactory interface.</P>
<A id="tests"></A>
<P></P>
<H3 >Test/Example
Programs</H3>
<P>The SDO project does not include any proper sample programs at this
time (any volunteers?) but it does include a number of JUnit test cases,
some of which serve as good examples of how to use SDO APIs to perform
various tasks.</P>
<P>The following tests are particularly good SDO examples included in
the sdo.impl project:</P>
<UL>
<LI>
<P><STRONG>SimpleDynamicTestCase</STRONG> This program uses the SDO
XSDHelper.define() method to register a simple XML Schema based model
(simple.xsd). It then instantiates a DataObject instance (type Quote),
initializes several of its properties, and then serializes the instance
to an XML stream.</P>
</LI>
<LI class="gap">
<P><STRONG>MixedTypeTestCase</STRONG> This program shows how to uses
the Sequence API to create an XML instance which mixes arbitrary text
within the DataObject's XML structure. It uses the XML schema
complexType (MixedQuote) in mixed.xsd to define the SDO model.</P>
</LI>
<LI class="gap">
<P><STRONG>OpenTypeTestCase</STRONG> Uses an XML Schema complexType
with a wildcard (xsd:any) to illustrate how to work with and manipulate
an SDO open type. The type OpenQuote in open.xsd is used for this
example.</P>
</LI>
<LI class="gap">
<P><STRONG>SimpleCopyTestCase</STRONG> Uses the SDO CopyHelper to
create shallow and deep copies of the simple Quote model from
SimpleDynamicTest.</P>
</LI>
<LI class="gap">
<P><STRONG>SimpleEqualityTestCase</STRONG> Uses the SDO EqualityHelper
to perform deep and shallow equality checks.</P>
</LI>
<LI class="gap">
<P><STRONG>ChangeSummaryTestCase</STRONG> Creates a data graph with an
instance of type Quote (in simple.xsd) as the root object. It then
turns on change logging and makes a number of changes to the graph.
Finally, it turns off change logging and serializes the data graph.</P>
</LI>
<LI class="gap">
<P><STRONG>XSDHelperTestCase</STRONG> This program shows how the
XSDHelper.define() method can be called multiple times with the same
schema. The second (and subsequent) call simply returns an empty list
since no new types are defined.</P>
</LI>
</UL>
<P>The following is in the sdo.tools project:</P>
<UL>
<LI>
<P><STRONG>SimpleStaticTestCase</STRONG> - This test performs the same
function as SimpleDynamicTestCase, above, only using a generated
version of the simple.xsd model. The generated model has been
pre-generated (with default options) in the directory src/test, but it
can be regenerated using the XSD2JavaGenerator, possibly with different
generator options (e.g., -noInterfaces or -sparsePattern), if desired.
</P>
</LI>
<LI class="gap">
<P><STRONG>StaticSequenceNoEmfTest</STRONG> This test exercises the
-noEMF generator option with a set of complex types, focussing on
Sequenced behaviour in the generated classes. The generated model has
been pre-generated (with options -noEMF -javaPackage
com.example.noemf.sequences) in the directory src/test, but it can be
regenerated using the XSD2JavaGenerator, possibly with different
generator options (e.g., -noInterfaces or -sparsePattern), if desired.
</P>
</LI>
</UL>
</section>
</body>
</document>
|
