db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject cvs commit: jakarta-ojb/xdocs tutorial4.xml
Date Tue, 17 Dec 2002 20:48:55 GMT
thma        2002/12/17 12:48:55

  Modified:    xdocs    tutorial4.xml
  Log:
  polishing JDO tutorial
  
  Revision  Changes    Path
  1.7       +164 -111  jakarta-ojb/xdocs/tutorial4.xml
  
  Index: tutorial4.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-ojb/xdocs/tutorial4.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- tutorial4.xml	17 Oct 2002 19:41:07 -0000	1.6
  +++ tutorial4.xml	17 Dec 2002 20:48:55 -0000	1.7
  @@ -13,12 +13,13 @@
   
   <subsection name="Introduction">
   
  -<p>This document demonstrates how to use the ObJectRelationalBridge (OJB) JDO
  -  Api in a simple application scenario. The tutorial application implements a
  +<p>
  +  This document demonstrates how to use ObjectRelationalBridge an the JDO API 
  +  in a simple application scenario. The tutorial application implements a
     product catalog database with some basic use cases. The source code for the
     tutorial application is shipped with the OJB source distribution and resides
  -  in the package <b><code>org.apache.ojb.tutorial4</code></b>.
  -  </p>
  +  in the directory <b><code>src/jdori/org/apache/ojb/tutorial5</code></b>.
  +</p>
   <p>
     The application scenario and the overall architecture have been introduced
     in the <A HREF="tutorial1.html">first part of this tutorial</A> and won't
be
  @@ -27,23 +28,45 @@
     The present document explains these modifications.
   </p>
   <p>
  -This document is not meant as a complete introduction to the JDO
  -standard.  For more information see: <A HREF="http://access1.sun.com/jdo/"><B>Sun's
JDO site</B></A>.
  +  This document is not meant as a complete introduction to JDO.  
  +  For more information see: <A HREF="http://java.sun.com/products/jdo/">Sun's JDO
site</A>.
   </p>
  -</subsection>
  -
  -<subsection name="see it running...">
   <p>
  -	To see the tutorial application at work you first have to compile the sources
  -	and to setup the test database
  -  	by executing <code>bin\build prepare-tutorials</code> under Win32 or
  -  	<code>bin/build.sh prepare-tutorials</code> under Unix/Linux
  -  	from the ojb toplevel directory.
  +	<b>temporary note:</b> OJB does not provide it's own JDO implementation yet.
  +	A full JDO implementation is in the scope of the 2.0 release.
  +	For the time being we provide a plugin to the JDO reference implementation 
  +	called <code>OjbStore</code>. The <code>OjbStore</code> plugin
resides in
  +	the package <code>org.apache.ojb.jdori.sql</code>.
   </p>
  +</subsection>
  +
  +<subsection name="Running the Tutorial Application">
   <p>
  -    Now you can start the tutorial application by executing
  -    <code>bin\tutorial4</code> or <code>bin/tutorial4.sh</code>
  -    from the ojb toplevel directory.
  +	To install and run the demo application please follow the following steps:
  +	<ol>
  +		<li>
  +			Download the JDO Specification and the Reference Implementation from 
  +			<A HREF="http://java.sun.com/products/jdo/">Sun's JDO site</A>.<br/>
  +			Extract the archives to local directories and copy the files 
  +			<b><code>jdori.jar</code></b>, <b><code>jdo.jar</code></b>
and
  +			<b><code>jdori-enhancer.jar</code></b> into the OJB <b><code>lib</code></b>
  +			directory.			
  +		</li>
  +		<li>
  +			Now compile the sources, setup the test database and perform bytecode
  +			enhancement
  +		  	by executing <code>bin\build with-jdori prepare-tutorials enhance-jdori</code>

  +		  	under Win32 or
  +		  	<code>bin/build.sh with-jdori prepare-tutorials enhance-jdori</code> under
Unix/Linux
  +		  	from the ojb toplevel directory.
  +	  	</li>	  	
  +
  +		<li>
  +		    Now you can start the tutorial application by executing
  +		    <code>bin\tutorial5</code> or <code>bin/tutorial5.sh</code>
  +		    from the ojb toplevel directory.
  +	    </li>
  +    </ol>
   </p>
   </subsection>
   </section>
  @@ -53,16 +76,18 @@
   <p>
   In the <A HREF="tutorial1.html">first tutorial</A> you learned
   that OJB provides three major APIs. The PersistenceBroker, the ODMG
  -implementation, and the JDO implementation. The first tutorial implemented the sample
  -applications use cases with the PersistenceBroker API. This tutorial
  -will show how the same use cases can be implemented using the JDO
  -API.
  +implementation, and the JDO implementation. 
   </p>
   <p>
  -You can get more information about the JDO API at <a href="http://access1.sun.com/jdo/"
target="_blank">http://access1.sun.com/jdo/</a>.
  -The OJB implementation of the JDO API resides in
  -the package <code>org.apache.ojb.jdo</code>.
  -
  +	The first tutorial implemented the sample
  +	applications use cases with the PersistenceBroker API. This tutorial
  +	will show how the same use cases can be implemented using the JDO
  +	API.
  +</p>
  +<p>
  +	You can get more information about the JDO API at 
  +	<a href="http://java.sun.com/products/jdo/javadocs/index.html" target="_blank">
  +	http://java.sun.com/products/jdo/javadocs/index.html</a>.
   </p>
   <subsection name="Obtaining the JDO PersistenceManager Object">
   <p>
  @@ -73,12 +98,16 @@
   
   A Vendor of an JDO compliant product must provide a specific
   implementation of the <code>javax.jdo.PersistenceManager</code>
  -interface. If
  -you know how to use the JDO API you only have to learn how to obtain
  -the OJB specific PersistenceManager object.
  +interface. JDO also specifies that a JDO implementation must provide a 
  +<code>javax.jdo.PersistenceManagerFactory</code> implementation that is 
  +responsible for generating <code>javax.jdo.PersistenceManager</code> 
  +instances.
  +So if you know how to use the JDO API you only have to learn how to obtain
  +the OJB specific PersistenceManagerFactory object. Ideally this will be 
  +the only vendor specific operation.
   </p>
   <p>
  -In our tutorial application the PersistenceManager object is
  +In our tutorial application the <code>PersistenceManagerFactory</code> object
is
   obtained in the constructor of the Application class and reached to
   the use case implementations for further usage:
   </p>
  @@ -86,39 +115,37 @@
   <source><![CDATA[
       public Application()
       {
  -        private PersistenceManagerFactory factory;
  -        private PersistenceManager manager;
  +    	factory = null;
  +        manager = null;
           try
           {
  -            factory = PersistenceManagerFactoryImpl.getInstance();
  -            manager = factory.getPersistenceManager();
  -
  +            // create OJB specific factory:
  +            factory = new OjbStorePMF();
           }
  -        catch (Exception ex)
  +        catch (Throwable t)
           {
  -            ex.printStackTrace();
  +            System.out.println("ERROR: " + t.getMessage());
  +            t.printStackTrace();
           }
           useCases = new Vector();
  -        useCases.add(new UCListAllProducts(manager));
  -        useCases.add(new UCEnterNewProduct(manager));
  -        useCases.add(new UCEditProduct(manager));
  -        useCases.add(new UCDeleteProduct(manager));
  -        useCases.add(new UCQuitApplication(manager));
  +        useCases.add(new UCListAllProducts(factory));
  +        useCases.add(new UCEnterNewProduct(factory));
  +        useCases.add(new UCEditProduct(factory));
  +        useCases.add(new UCDeleteProduct(factory));
  +        useCases.add(new UCQuitApplication(factory));
       }
   ]]></source>
   <p>
  -The class <code>org.apache.ojb.jdo.PersistenceManagerFactoryImpl</code> is
  -the OJB specific <code>javax.jdo.PersistenceManagerFactory</code>
  -and provides a static factory method <code>getInstance()</code>.
  -The obtained instance is then used to create a
  -<code>javax.jdo.PersistenceManager</code>.
  +The class <code>org.apache.ojb.jdori.sql.OjbStorePMF</code> is
  +the OJB specific <code>javax.jdo.PersistenceManagerFactory</code> 
  +implementation.
   </p>
   <p>
   TODO: Put information about the .jdo files
   </p>
   <p>
  -The PersistenceManager object is reached to the constructors of the
  -UseCases. These constructors store it in a protected attribute <code>manager</code>
  +The <code>PersistenceManagerFactory</code> object is reached to the constructors
of the
  +UseCases. These constructors store it in a protected attribute <code>factory</code>
   for further usage.
   </p>
   
  @@ -143,40 +170,60 @@
   	does not need any limiting search criteria.
   </p>
   <p>
  -	In the first step we ask the PersistenceManager to create a query
  +	We use the factory to create a PersistenceManager instance in step one.
  +	In the second step we ask the PersistenceManager to create a query
   	returning all Product instances.	
   </p>
   
   <p>
  -	In the second step we perform the query and collect the results in a
  +	In the third step we perform the query and collect the results in a
   	collection.
   </p>
   <p>
  -	In the third step we iterate through the collection to print out
  +	In the fourth step we iterate through the collection to print out
   	each product matching our query.
   </p>
   <source><![CDATA[
       public void apply()
       {
  +    public void apply()
  +    {
  +        // 1. get a PersistenceManager instance 
  +        PersistenceManager manager = factory.getPersistenceManager();
           System.out.println("The list of available products:");
  -        // 1. build a query that select all objects of Class Product
  -        Query query = manager.newQuery(Product.class);
  +
           try
           {
  -            // 2. execute query and store results
  -            Collection allProducts = (Collection)query.execute();
  +            // clear cache to provoke query against database
  +            PersistenceBrokerFactory.defaultPersistenceBroker().clearCache();
  +        	
  +            // 2. start tx and form query
  +            manager.currentTransaction().begin();
  +            Query query = manager.newQuery(Product.class);
  +
  +            // 3. perform query
  +            Collection allProducts = (Collection)query.execute(); 
               
  -            // 3. iterate over the results to print each product
  +            // 4. now iterate over the result to print each product and finish tx
               java.util.Iterator iter = allProducts.iterator();
  +            if (! iter.hasNext())
  +            {
  +            	System.out.println("No Product entries found!");	
  +            }
               while (iter.hasNext())
               {
                   System.out.println(iter.next());
               }
  +            manager.currentTransaction().commit();
           }
           catch (Throwable t)
           {
               t.printStackTrace();
           }
  +        finally
  +        {
  +        	manager.close();	
  +        }
       }
   ]]></source>
   
  @@ -224,18 +271,20 @@
           in = readLineWithMessage("enter available stock:");
           newProduct.setStock(Integer.parseInt(in));
   
  -        // now perform persistence operations
  +        // 3. create PersistenceManager and start transaction
  +        PersistenceManager manager = factory.getPersistenceManager();
           
  -        // 3. open transaction
           Transaction tx = null;
           tx = manager.currentTransaction();
           tx.begin();
  -		
  -        // 4. make object persistent
  +
  +        // 4. mark object as persistent
           manager.makePersistent(newProduct);
           
           // 5. commit transaction
           tx.commit();
  +        
  +        manager.close();
       }
   ]]></source>
   
  @@ -257,14 +306,7 @@
   	The product is then edited (Step 3.).
   </p>
   <p>
  -	In step four a transaction object is obtained. 
  -</p>
  -<p>
  -	We then have to ask the PersistenceManager to make the object persistent.
  -	This is done in step five.
  -</p>
  -<p>
  -	In the last step we commit the transaction. All changes to objects
  +	In step four the transaction is commited. All changes to objects
   	touched by the transaction are now made persistent. 
       Because we modified an existing object an update operation is
       performed against the backend database.
  @@ -272,30 +314,33 @@
   <source><![CDATA[
       public void apply()
       {
  +    	PersistenceManager manager = null;
           String in = readLineWithMessage("Edit Product with id:");
           int id = Integer.parseInt(in);
   
  +        // We don't have a reference to the selected Product.
  +        // So first we have to lookup the object,
   
           Product toBeEdited;
  -
  -
           try
           {
  -           // 1. Build a query to look up product with id
  -            Query query = manager.newQuery(Product.class, "id == " + id);
  -
  -            // 2. execute query and see if any results were returned
  -            Collection results = (Collection) query.execute ();
  -
  -                Iterator iter = results.iterator();
  -                if(iter.hasNext()){
  -                    toBeEdited = (Product)iter.next();
  -                }
  -                else{
  -                    System.out.println("Product Not Found.  Please try again.");
  -                    return;
  -                }
  -
  +            manager = factory.getPersistenceManager();
  +			
  +            // 1. create Identity representing the instance to edit.
  +            Product example = new Product();
  +            example.setId(id);
  +            Identity oid = new Identity(example);
  +            
  +            // 2. start tx and retrieve instance by identity lookup
  +            manager.currentTransaction().begin();
  +            toBeEdited = (Product) manager.getObjectById(oid, false);
  +            if (toBeEdited == null)
  +            {
  +            	System.out.println("did not find a matching instance...");
  +            	manager.currentTransaction().rollback();
  +            	return;	
  +            }
  +            
               // 3. edit the existing entry
               System.out.println("please edit the product entry");
               in =
  @@ -313,22 +358,19 @@
                           + "):");
               toBeEdited.setStock(Integer.parseInt(in));
   
  -            // 4. open transaction
  -            Transaction tx = null;
  -            tx = manager.currentTransaction();
  -            tx.begin();
  -
  -            // 5. mark object for update
  -            manager.makePersistent(toBeEdited);
  -
  -            // 6. commit transaction
  -            tx.commit();
  +            // 4. commit transaction. changes to toBeEdited are made persistent
  +            manager.currentTransaction().commit();
           }
           catch (Throwable t)
           {
  +            // rollback in case of errors
               manager.currentTransaction().rollback();
               t.printStackTrace();
           }
  +        finally 
  +        {
  +        	manager.close();	
  +        }
       }
   ]]></source>
   
  @@ -347,11 +389,8 @@
   	application does not hold a list of all product objects.
   </p>
   <p>
  -	In the third step we obtain a fresh transaction and start it.
  -</p>
  -<p>
  -	We then have to ask the PersistenceManager to delete the persistent object.
  -	This is done in step four.
  +	In the third step we ask the PersistenceManager to 
  +	delete the persistent object.
   </p>
   <p>
   	In the last step we commit the transaction. All changes to objects
  @@ -363,28 +402,41 @@
   <source><![CDATA[
       public void apply()
       {
  +    	PersistenceManager manager = null;
           String in = readLineWithMessage("Delete Product with id:");
           int id = Integer.parseInt(in);
   
  -        // 1. build an example object with matching primary key values:
  +        // We don't have a reference to the selected Product.
  +        // 1. build an Identity representing the instance in question
           Product example = new Product();
           example.setId(id);
  +        Identity oid = new Identity(example);
           try
           {
  -            // 2. lookup object to be edited
  -            Product toBeDeleted =
  -                (Product) manager.getObjectById(example, false);
  -                
  -            // 3. open transaction
  +            // 2. obtain PM, start tx and perform identity lookup
  +            manager = factory.getPersistenceManager();
  +            
  +            // start transaction
               Transaction tx = null;
  +            // open transaction
               tx = manager.currentTransaction();
               tx.begin();
   
  -            // 4. ask PersistenceManager to delete the object
  +            Product toBeDeleted =
  +                (Product) manager.getObjectById(oid, false);
  +            if (toBeDeleted == null)
  +            {
  +            	System.out.println("did not find a matching instance...");
  +            	tx.rollback();
  +            	return;	
  +            }
  +            // 3. mark object as deleted
               manager.deletePersistent(toBeDeleted);
   
  -            // 5. commit transaction
  +            // commit transaction. A DELETE statement is generated and executed to
  +            // remove toBeDeleted from the database
               tx.commit();
  +            manager.close();
           }
           catch (Throwable t)
           {
  @@ -393,6 +445,7 @@
               t.printStackTrace();
           }
       }
  +
   ]]></source>
   
   </subsection>
  @@ -400,9 +453,9 @@
   
   <section name="Conclusion">
   <p>
  -In this tutorial you learned to use the standard JDO API as
  -implemented by the OJB system within a simple application scenario. I
  -hope you found this tutorial helpful. Any comments are welcome.
  +	In this tutorial you learned to use the standard JDO API as
  +	implemented by the OJB system within a simple application scenario. I
  +	hope you found this tutorial helpful. Any comments are welcome.
   </p>
   
   </section>
  
  
  

Mime
View raw message