diff options
Diffstat (limited to 'tags/site-090106-pre667/site-publish/java_sdo_overview.html')
| -rw-r--r-- | tags/site-090106-pre667/site-publish/java_sdo_overview.html | 839 |
1 files changed, 0 insertions, 839 deletions
diff --git a/tags/site-090106-pre667/site-publish/java_sdo_overview.html b/tags/site-090106-pre667/site-publish/java_sdo_overview.html deleted file mode 100644 index 3534ca09ec..0000000000 --- a/tags/site-090106-pre667/site-publish/java_sdo_overview.html +++ /dev/null @@ -1,839 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-
-<!--
-Copyright 1999-2004 The Apache Software Foundation
-Licensed 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.
--->
-
-
-<!-- Content Stylesheet for Site -->
-
-
-<!-- start the processing -->
-<!-- ====================================================================== -->
-<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
-<!-- Main Page Section -->
-<!-- ====================================================================== -->
-<html>
-<head>
- <link rel="stylesheet" href="./css/base.css"/>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
-
- <meta name="author" value="Kelvin Goodson">
- <meta name="email" value="kelvingoodson+tuscanysite@gmail.com">
-
-
-
-
- <title>Tuscany - Java SDO Overview</title>
-</head>
-
-<body bgcolor="#ffffff" text="#000000" link="#525D76">
- <table border="0" width="100%" cellspacing="0">
- <!-- TOP IMAGE -->
- <tr>
- <td align='LEFT'><td align="left">
-<a href="http://incubator.apache.org/tuscany/"><img src="./images/tuscanylogo_candidate2.jpg" alt="Tuscany" border="0" height="32" width="120"/></a>
-</td>
-</td>
- <td align='LEFT'><td width="80%" align="left" valign="bottom" bgcolor="#ffffff">
- <font color="#625972" size="+3" face="arial,helvetica,sanserif">
- <b><bannertitle>Java SDO Overview</bannertitle></b>
-</font>
-</td>
-</td>
- </tr>
- </table>
- <hr noshade="" size="1"/>
- <table border="0" cellspacing="0">
- <tr>
- <td> <a href="./index.html">Home</a>
-</td>
- <td> <a href="./sca_index.html">SCA</a>
-</td>
- <td> <a href="./sdo_index.html">SDO</a>
-</td>
- <td> <a href="./das_index.html">DAS</a>
-</td>
- </tr>
- </table>
- <table border="0" width="100%" cellspacing="4">
- <tr>
- <!-- LEFT SIDE NAVIGATION -->
- <td width="20%" valign="top" nowrap="true">
-
- <!-- ============================================================ -->
-
- <p><strong>General</strong></p>
- <ul>
- <li> <a href="./index.html">Home</a>
-</li>
- <li> <a href="./news.html">News</a>
-</li>
- <li> <a href="./documentation.html">Documentation</a>
-</li>
- <li> <a href="./license.html">License</a>
-</li>
- <li> <a href="http://www.apache.org/" target="_blank">ASF</a>
-</li>
- <li> <a href="./downloads.html">Downloads</a>
-</li>
- </ul>
- <p><strong>Community</strong></p>
- <ul>
- <li> <a href="./get-involved.html">Get Involved</a>
-</li>
- <li> <a href="./mail-lists.html">Mailing Lists</a>
-</li>
- <li> <a href="./faq.html">FAQ</a>
-</li>
- <li> <a href="./issue-tracking.html">Issue Tracking</a>
-</li>
- <li> <a href="http://wiki.apache.org/ws/Tuscany" target="_blank">Wiki</a>
-</li>
- <li> <a href="http://apache-tuscany.blogspot.com" target="_blank">Blog</a>
-</li>
- </ul>
- <p><strong>Development</strong></p>
- <ul>
- <li> <a href="http://wiki.apache.org/ws/Tuscany/TuscanyJava/Roadmap" target="_blank">Road Map / TODO</a>
-</li>
- <li> <a href="./source-code.html">Source Code</a>
-</li>
- <li> <a href="./java-projects.html">Java projects</a>
-</li>
- <li> <a href="./cpp-projects.html">C++ projects</a>
-</li>
- </ul>
- </td>
- <td width="80%" align="left" valign="top">
- <table border="0" cellspacing="0" cellpadding="2" width="100%">
- <tr><td bgcolor="#726982">
- <font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="Service Data Objects"><strong>Service Data Objects</strong></a>
- </font>
- </td></tr>
- <tr><td>
- <blockquote>
- <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>
- <H3>Overview</H3>
- <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://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-sdo/SDO_Specification_Java_V2.01.pdf"> 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="http://incubator.apache.org/tuscany/java-projects.html"> these instructions</A>.</P>
- <H4>SDO Java Build -Environment Setup</H4>
- <P>If you want to work with the SDO 2 project 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="http://incubator.apache.org/tuscany/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 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 <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 <BR /> - mvn <BR /> - mvn 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 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 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 build both sdo.impl and sdo.tools 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 sdo-api-SNAPSHOP.jar is created under - <local tuscany dir>/java/spec/sdo/target directory.</P> - </LI> - <LI> - <P>External 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 three 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> -</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"> -https://svn.apache.org/repos/asf/incubator/tuscany/java/spec/sdo</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.0-SNAPSHOT.jar - some common framework utility and - base classes</P> - </LI> - <LI> - <P>emf-ecore-2.2.0-SNAPSHOT.jar - the EMF core runtime implementation - classes (the Ecore metamodel)</P> - </LI> - <LI> - <P>emf-ecore-change-2.2.0-SNAPSHOT.jar - the EMF change recorder and - framework</P> - </LI> - <LI> - <P>emf-ecore-xmi-2.2.0-SNAPSHOT.jar - EMF's default XML (and XMI) - serializer and loader</P> - </LI> - <LI> - <P>xsd-2.2.0-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.0-SNAPSHOT.jar - template-based codegen framework - (JET - Java Emitter Templates)</P> - </LI> - <LI> - <P>emf-codegen-ecore-2.2.0-SNAPSHOT.jar - the EMF code generator</P> - </LI> - <LI> - <P>emf-common-2.2.0-SNAPSHOT.jar - some common framework utility and - base classes</P> - </LI> - <LI> - <P>emf-ecore-2.2.0-SNAPSHOT.jar - the EMF core runtime implementation - classes (the Ecore metamodel)</P> - </LI> - <LI> - <P>emf-ecore-change-2.2.0-SNAPSHOT.jar - the EMF change recorder and - framework</P> - </LI> - <LI> - <P>emf-ecore-xmi-2.2.0-SNAPSHOT.jar - EMF's default XML (and XMI) - serializer and loader</P> - </LI> - <LI> - <P>xsd-2.2.0-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).</P>
- <A id="runtime" />
- <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" />
- <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. 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" />
- <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>
- </blockquote>
- </p>
- </td></tr>
- <tr><td><br/></td></tr>
- </table>
- </td>
- </tr>
- </table>
- <hr noshade="" size="1"/>
- <table border="0" width="100%" cellspacing="0">
- <tr>
- <td><img src="./images/apache-incubator-logo.png" alt="Apache Incubator Logo"/></td>
- <td class="disclaimer">
- <em>Copyright © 2006, The Apache Software Foundation</em><br/>
- Apache Tuscany is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Web Services PMC.
- Incubation is required of all newly accepted projects until a further review indicates that the infrastructure,
- communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.
- While incubation status is not necessarily a reflection of the completeness or stability of the code,
- it does indicate that the project has yet to be fully endorsed by the ASF.
- </td>
- </tr>
- </table>
-</body>
-</html>
-<!-- end the processing -->
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
|