You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@labs.apache.org by pp...@apache.org on 2007/07/26 23:37:32 UTC
svn commit: r559996 - in /labs/fluid/src: site/apt/convert_type.apt
site/apt/enhance_type.apt site/apt/generate_type.apt site/apt/manual.apt
site/apt/persist_type.apt test/java/example/basic/TestCRUD.java
test/java/example/basic/TestRelation.java
Author: ppoddar
Date: Thu Jul 26 14:37:31 2007
New Revision: 559996
URL: http://svn.apache.org/viewvc?view=rev&rev=559996
Log:
Preparing Site links
Added:
labs/fluid/src/site/apt/convert_type.apt
labs/fluid/src/site/apt/enhance_type.apt
labs/fluid/src/site/apt/generate_type.apt
labs/fluid/src/site/apt/persist_type.apt
Modified:
labs/fluid/src/site/apt/manual.apt
labs/fluid/src/test/java/example/basic/TestCRUD.java
labs/fluid/src/test/java/example/basic/TestRelation.java
Added: labs/fluid/src/site/apt/convert_type.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/convert_type.apt?view=auto&rev=559996
==============================================================================
--- labs/fluid/src/site/apt/convert_type.apt (added)
+++ labs/fluid/src/site/apt/convert_type.apt Thu Jul 26 14:37:31 2007
@@ -0,0 +1,88 @@
+{Mapping SDO Types to Java source code}
+
+* {Generate Plain, Old, Java Objects from SDO}
+
+ SDO Types specified in XML Schema Definition (*.xsd) files can be converted
+ to Java classes annotated for persistence.
+
++----------------------------------------------------------------
+ $ java org.apache.openjpa.sdo.SDO2POJOGenerator person.xsd
++----------------------------------------------------------------
+
+ will convert one or more SDO types specified in <<<person.xsd>>>, annotate
+ them for persitence and save them in corresponding <<<*.java>>> file. The
+ generated Java source files are written relative to the current directory.
+
+ Specify <<<-rootDirectory>>> or simply <<<-d>>> option to write to another
+ location in the disk. For example,
+
++----------------------------------------------------------------
+ $ java org.apache.openjpa.sdo.SDO2POJOGenerator -d generated/src/ p.xsd q.xsd
++----------------------------------------------------------------
+
+ will convert SDO Types from both <<<p.xsd>>> and <<<q.xsd>>> to Java source
+ code and write them to a directory relative to <<<generated/src/>>>.
+
+* Rules of SDO to POJO mapping
+
+ The SDO Type are mapped isomorphically to Java classes (with one exception).
+
+ * Each property of primitive xsd type is converted to Java field of same name
+ and decalred type is as specified by SDO specification for primitive type
+ conversion. {{LINK}}
+
+ * Each single-valued property of user defined type X is converted to a relation
+ field of Java equivalent for type X.
+
+ * Each multi-valued property of user defined type X is converted to a relation
+ field of <<<java.util.List>>> whose element is Java equivalent of type X.
+
+ * One exception is made for <<Container>> type. Container type is defined as
+ a SDO Type that has <<one and only one>> many-valued Property of user-defined
+ type. This single property is referred as <<component>> type.
+
+ * All Java fields will be private with bean-style getter and setter methods.
+
+ No Java source code is generated for Container type.
+
+ The property of Container type is mapped as <<<java.util.List>>> whose
+ element is Java equivalent of component type.
+
+* Added JPA Annotation
+
+ The generated Java source code is annotated with JPA annotations.
+
+ * The generated class is marked as <<<...@Entity>>>
+
+ * Identity field is annotated with <<<...@Id>>> and <<<...@GeneratedValue>>>
+
+ * Version field is annotated with <<<...@Version>>>
+
+ * Single-valued field is annoted with <<<...@OneToOne>>>
+
+ * Many-valued field and container field is annotated with <<<...@OneToMany>>>
+
+
+
+* Using Package name for generated Java source
+
+ Java package name for SDO Types can be specified in
+ <<<sdoJava:package>>> in <<<*.xsd>>> header. For example,
+
++---------------------------------------
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:example="http://www.example.com/Example"
+ targetNamespace="http://www.example.com/Example"
+
+ xmlns:sdo="commonj.sdo"
+ xmlns:sdoJava="commonj.sdo/java"
+ sdoJava:package="example.domain">
+
+ <xsd:complexType name="Person">
+ ....
++---------------------------------------
+
+ will generate a Java class with fully-qualified name
+ <<<example.domain.Person>>>.
+
+
\ No newline at end of file
Added: labs/fluid/src/site/apt/enhance_type.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/enhance_type.apt?view=auto&rev=559996
==============================================================================
--- labs/fluid/src/site/apt/enhance_type.apt (added)
+++ labs/fluid/src/site/apt/enhance_type.apt Thu Jul 26 14:37:31 2007
@@ -0,0 +1,8 @@
+Enhancing generated Java Source Code
+
+ Generated Java source code can be compiled with <<<javax.persistence.*>>>
+ classes in the classpath because of persistence annotations.
+
+ Once the generated source code is compiled, they are to be enhanced for using
+ with OpenJPA. OpenJPA enhancement process is described in
+ {{{http://openjpa.apache.org/docs/latest/manual/manual.html#ref_guide_pc_enhance}OpenJPA User Guide}}
\ No newline at end of file
Added: labs/fluid/src/site/apt/generate_type.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/generate_type.apt?view=auto&rev=559996
==============================================================================
--- labs/fluid/src/site/apt/generate_type.apt (added)
+++ labs/fluid/src/site/apt/generate_type.apt Thu Jul 26 14:37:31 2007
@@ -0,0 +1,144 @@
+{Decorating SDO Type for Persistence}
+
+* {basic}Basics of SDO Types
+
+ SDO defines its type system in terms of two abstractions <<<Type>>> and
+ <<<Property>>> captured in SDO API as <<<commonj.sdo.Type>>> and
+ <<<commonj.sdo.Property>>> interfaces.
+
+ A <<<Type>>> can be
+
+ * primitive data type such as <<<xsd:int>>> or <<<xsd:string>>>
+
+ * an extension of primitive type
+
+ * a user defined type
+
+ Each Property has a Type. A Property can be single-valued or many-valued.
+ It can be contained in an enclosing Type. A Property can be read-only.
+ These features of Type or Property are available through interogative
+ methods such as <<<Type.isAbstract()>>>, <<<Type.isDataType()>>> or
+ <<<Property.isMany()>>>.
+
+ SDO Types can be generated from XML Schema Definition.
+ A very simple example of XML Schema Definition that can be used for SDO Type
+ can be defined in a <<<person.xsd>>>:
+
+
++------------------------------------------------------------------------
+ <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:example="http://www.example.com/Example"
+ targetNamespace="http://www.example.com/Example"
+ xmlns:sdo="commonj.sdo">
+
+ <xsd:complexType name="Person">
+ <xsd:sequence>
+ <xsd:element name="firstName" type="xsd:string"/>
+ <xsd:element name="lastName" type="xsd:string"/>
+ <xsd:element name="age" type="xsd:int"/>
+ </xsd:sequence>
+ <xsd:attribute name="ssn" type="xsd:ID"/>
+ <xsd:attribute name="version" type="xsd:int"/>
+ </xsd:complexType>
+</xsd:schema>
+
++------------------------------------------------------------------------
+
+ SDO API provides a XSDHelper object that can read a XML Schema Definition file
+ and define SDO Type <<<Person>>> from this definition.
+
+* {prepare}Adding Property to SDO Types for persistence
+
+ If instances of SDO Types are to be persisted and updated, two pieces of
+ information becomes vital: <identity> and <version>.
+ SDO Specification version 2.0 does not specify how to designated Property of
+ a Type to carry identity or version information.
+
+ Hence, we devise a simple way described here.
+
+** {identity}Adding Identity Property
+
+ Unlike a database table definition that specifies a
+ <primary key> to uniquely identify its rows, SDO Type does not specify a
+ property whose value will uniquely identify an instance of that type. XML
+ schema definition, however, defines <<<xsd:ID>>>, <<<xsd:key>>> and
+ <<<xsd:keyRef>>> for the purpose of unique identification of SDO instances.
+
+ Persistent SDO Type <<must>> specify a identity property in either of the
+ follwing two ways.
+
+ [[A]] Define a Property of <<<xsd:ID>>> type
+
+ One way is to designate a Property of <<<xsd:ID>>> type. For example,
+
++-------------------------------------------------------------------
+ <xsd:attribute name="ssn" type="xsd:ID"/>
++-------------------------------------------------------------------
+
+ <<<xsd:ID>>> types represent the value as String, so the value of <<<ssn>>>
+ property will be stored as a String.
+
+ [[B]] Define a Property with name <<<id>>>
+
+ The other option to define a identity property (which is not neccessarily a
+ String) is declare a property with name <<<id>>> (yes, it is harcoded,
+ right now) and of primitive type. For example,
+
++-------------------------------------------------------------------
+ <xsd:attribute name="id" type="xsd:int"/>
++-------------------------------------------------------------------
+
+ will deine <<<id>>> as identity property for <<<Person>>> and value of
+ <<<id>>> will be integers.
+
+*** Why <<<xsd:key>>> type is not used for Identity?
+
+ <<<xsd:key>>> is the right semantics to define a <<identity property>> for
+ SDO Type. However, <<<xsd:ID>>> is used because of an implementation
+ artifact.
+
+ Currently, SDO API does neither provide the identity property for a Type nor a
+ means to determine the original xsd type for a Property (it is going to change
+ in future SDO API specification). A specific SDO implementation may have some
+ means to obtain that information. Tuscany SDO Implementation used here provides
+ a way to determine whether a Property is declared as <<<xsd:ID>>>. Simply
+ because of this reason, we use <<<xsd:ID>.> rather than <,<<xsd:key>>> to
+ define identity property of a SDO Type.
+
+
+** {version}Adding Version Property
+
+ A version property is required for update. JPA persistence service uses
+ optimistic concurrency -- persistent instances
+ are not locked in database and but concurrent modifications are detected
+ by checking the version of in-memory instances against original database
+ record. This is vital when a DataObject is updated. JPA provider will use
+ the version information to determine whether the instance to be updated or
+ a new instance to be created.
+
+ The version property is simply defined by declaring a
+ property named <<<version>>> of <<<xsd:int>>> on SDO Type.
+
++-------------------------------------------------------------------
+ <xsd:complexType name="Person">
+ <!-- other definitions ommitted -->
+ <xsd:attribute name="version" type="xsd:int"/>
+ </xsd:complexType>
++-------------------------------------------------------------------
+
+ The property <must> be named <<<version>>> and always of type <<<xsd:int>>>.
+ This is arbitrary decision but will be relaxed in future.
+
+** Identity and Version values are auto-generated
+
+ The value of identity and version property field is <<currently>> always
+ auto-generated by JPA persistence service when the DataObject is persisted.
+ So user application must not populate these values. Identity value set by
+ user application are ignored when the instance is persisted. Setting
+ version value will cause unpredictable behavior.
+
+
+
+
+
+
\ No newline at end of file
Modified: labs/fluid/src/site/apt/manual.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/manual.apt?view=diff&rev=559996&r1=559995&r2=559996
==============================================================================
--- labs/fluid/src/site/apt/manual.apt (original)
+++ labs/fluid/src/site/apt/manual.apt Thu Jul 26 14:37:31 2007
@@ -6,7 +6,7 @@
[[1.2]] References
- [[2]] {{{Usage}}Usage}
+ [[2]] {{{Usage}Usage}}
[[2.1]] {{{generate_type.html}Decorating SDO Type for persistence}}
@@ -14,9 +14,9 @@
[[2.2.1]] {{{generate_type.html#prepare}Adding Property to SDO Types for persistence}}
- [[2.2.1.1]] {{{generate_type.html#identity}Adding Identity Property
+ [[2.2.1.1]] {{{generate_type.html#identity}Adding Identity Property}}
- [[2.2.1.2]] {{{generate_type.html#version}Adding Version Property
+ [[2.2.1.2]] {{{generate_type.html#version}Adding Version Property}}
[[2.2]] {{{convert_type.html}Mapping SDO Types to Java source code}}
@@ -24,15 +24,17 @@
[[2.4]] {{{persist_type.html}Persistence operations with SDO DataObjects}}
- [[2.4.1]] {{{persist_type.html#store}Storing SDO DataObjects}}
+ [[2.4.0]] {{{persist_type.html#Configuring}Configuring for SDO Persistence}}
- [[2.4.2]] {{{persist_type.html#query}Querying SDO DataObjects
+ [[2.4.1]] {{{persist_type.html#Storing}Storing SDO DataObjects}}
+
+ [[2.4.2]] {{{persist_type.html#Querying}Querying SDO DataObjects}}
- [[2.4.3]] {{{persist_type.html#merge}Updating SDO DataObjects
+ [[2.4.3]] {{{persist_type.html#Updating}Updating SDO DataObjects}}
- [[2.4.4]] {{{persist_type.html#remove}Deleting SDO DataObjects
+ [[2.4.4]] {{{persist_type.html#Deleting}Deleting SDO DataObjects}}
- [[2.4.5]] {{{persist_type.html#find}Finding SDO DataObjects
+ [[2.4.5]] {{{persist_type.html#Finding}Finding SDO DataObjects}}
[[3]] Examples
Added: labs/fluid/src/site/apt/persist_type.apt
URL: http://svn.apache.org/viewvc/labs/fluid/src/site/apt/persist_type.apt?view=auto&rev=559996
==============================================================================
--- labs/fluid/src/site/apt/persist_type.apt (added)
+++ labs/fluid/src/site/apt/persist_type.apt Thu Jul 26 14:37:31 2007
@@ -0,0 +1,93 @@
+Persistence operations with SDO DataObjects
+
+ OpenJPA SDO extension works exactly as any other JPA application, exxcept that
+ the persistence unit is activated to process SDO Types and JPA interfaces accept
+ and return DataObjects as result of persistent operations such as
+ <<<persist()>>>, <<<merge()>>> or query.
+
+
+* {Configuring} for SDO Persistence
+
+ OpenJPA SDO extension is activated by configuring persistence configuration
+ file <<<META-INF/persistence.xml>>>. The persistence configuration file is
+ configured adding following properties under <<<<properties>>>> tag as follows:
+
++--------------------------------------------------------------------------
+ <property name="openjpa.EntityManagerFactory" value="sdo"/>
+ <property name="openjpa.MetaDataFactory" value="sdo(Resources=META-INF/person.xsd;META-INF/po.xsd;)"/>
++--------------------------------------------------------------------------
+
+ The <<<openjpa.EntityManagerFactory>>> property tells OpenJPA runtime to use
+ a EntityManager Factory specialized to handle SDO DataObjects.
+
+ The <<<openjpa.MetaDataFactory>>> property tells OpenJPA runtime where to look
+ for persistent classes. Normally, the persistent classes are listed in
+ <<<<class>>>> or <<<<jar>>>> tag. For SDO, specify one of more *.xsd files.
+ The file names are resolved against the current classpath.
+
+* {Storing} DataObjects
+
+ DataObjects are stored exactly as normal POJOs using JPA.
+ * Create a DataObject via helper instances in SDO API such as DataFactory.
+
+%{snippet|id=createPerson|url=http://svn.apache.org/repos/asf/labs/fluid/src/test/java/example/basic/TestCRUD.java}
+
+ * Invoke <<<EntityManager.persist()>>> on an active transaction.
+
+%{snippet|id=persist|url=http://svn.apache.org/repos/asf/labs/fluid/src/test/java/example/basic/TestCRUD.java}
+
+ The result of persist operation is <<transitive>>. It not only stores the
+ DataObject passed as argument but all other DataObjects reachable from it.
+
+* {Querying} DataObjects
+
+ DataObjects are queried using powerful JPA Query language JPQL (Java Persistence
+ Query Language}. The results of query is returned as a List of DataObjects as
+ shown in the example:
+
+%{snippet|id=createQuery|url=http://svn.apache.org/repos/asf/labs/fluid/src/test/java/example/basic/TestRelation.java}
+
+* {Updating} DataObjects
+
+ DataObjects are updated via <<<EntityManager.merge()>>>. The entire closure of
+ given DataObject is updated if modified and a merged DataObject is returned
+ to the caller as shown in the example:
+
+%{snippet|id=merge|url=http://svn.apache.org/repos/asf/labs/fluid/src/test/java/example/basic/TestRelation.java}
+
+
+* {Finding} DataObject by id
+
+ Finding a DataObject by identity departs slightly from <<<EntityManager.find()>>>
+ behavior. The signature of <<<EntityManager.find()>>> as defined by JPA
+ specification is
+
+ -------------------------------------------------------------
+ public <T> T find(Class<T> cls, Object id);
+ -------------------------------------------------------------
+
+ To use <<<find()>>> with SDO, the user must pass
+
+ * <<<DataObject.class>>> as the first argument
+
+ * The id must be a String that is prefixed with the SDO Type name. For example,
+ to find a <<<Customer>>> DataObject with an integer id <<<1234>>>, the caller
+ must supply the <<<id>>> argument to <<<find()>>> method as a String
+ <<<"Customer:1234">>>.
+
+%{snippet|id=find|url=http://svn.apache.org/repos/asf/labs/fluid/src/test/java/example/basic/TestCRUD.java}
+
+ The departure from normal JPA find method arises because SDO DataObject
+ represents a relaxed-type system as opposed to a
+ strong-type system in Java for which JPA is originally inteneded.
+
+ Normal Java behaviour would be calling <<<em.find(Customer.class, 1234);>>>.
+ But SDO extension to OpenJPA supports a client programming model where there
+ is <<no>> Customer class to begin with. Also <<<find()>>> return DataObject,
+ because of its method signature, it must accept <<<DataObject.class>>>. Hence,
+ the type of DataObject being looked up can not be passed via the first
+ argument (as it is possible when a concrete <<<Customer.class>>> could be
+ supplied). Hence, the convention of the identifier to be created with
+ Type name as prefix.
+
+
Modified: labs/fluid/src/test/java/example/basic/TestCRUD.java
URL: http://svn.apache.org/viewvc/labs/fluid/src/test/java/example/basic/TestCRUD.java?view=diff&rev=559996&r1=559995&r2=559996
==============================================================================
--- labs/fluid/src/test/java/example/basic/TestCRUD.java (original)
+++ labs/fluid/src/test/java/example/basic/TestCRUD.java Thu Jul 26 14:37:31 2007
@@ -31,13 +31,13 @@
int before = count("Person");
String ssn = ""+System.currentTimeMillis();
- // START SNIPPET:persistPerson
+ // START SNIPPET:persist
DataObject data = createPerson(ssn, "John", "Doe", 42);
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
em.persist(data);
em.getTransaction().commit();
- // END SNIPPET:persistPerson
+ // END SNIPPET:persist
int after = count("Person");
assertEquals(before+1, after);
Modified: labs/fluid/src/test/java/example/basic/TestRelation.java
URL: http://svn.apache.org/viewvc/labs/fluid/src/test/java/example/basic/TestRelation.java?view=diff&rev=559996&r1=559995&r2=559996
==============================================================================
--- labs/fluid/src/test/java/example/basic/TestRelation.java (original)
+++ labs/fluid/src/test/java/example/basic/TestRelation.java Thu Jul 26 14:37:31 2007
@@ -52,12 +52,10 @@
String jpql = "SELECT o FROM PurchaseOrderType o WHERE o.shipTo.name=:name";
Query query = em.createQuery(jpql);
query.setParameter("name", "Alice Smith");
- List result = query.getResultList();
+ List<DataObject> result = query.getResultList();
// END SNIPPET:createQuery
assertFalse(result.isEmpty());
- for (Object o : result) {
- assertTrue(o.getClass() + " is not DataObject", o instanceof DataObject);
- DataObject dataObject = (DataObject) o;
+ for (DataObject dataObject : result) {
assertEquals("PurchaseOrderType", dataObject.getType().getName());
DataObject shipTo = dataObject.getDataObject("shipTo");
String name = shipTo.getString("name");
@@ -93,7 +91,7 @@
int after = count("USAddress");
assertEquals(before, after);
}
- // START SNIPPET:merge
+ // END SNIPPET:merge
}
/**
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@labs.apache.org
For additional commands, e-mail: commits-help@labs.apache.org