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