db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bri...@apache.org
Subject cvs commit: db-ojb/xdocs odmg-tutorial.xml
Date Tue, 30 Sep 2003 19:29:16 GMT
brianm      2003/09/30 12:29:16

  Added:       src/test/org/apache/ojb/tutorials ODMGExample.java
               xdocs    odmg-tutorial.xml
  Log:
  Initial ODMG tutorial checkin
  
  Revision  Changes    Path
  1.1                  db-ojb/src/test/org/apache/ojb/tutorials/ODMGExample.java
  
  Index: ODMGExample.java
  ===================================================================
  package org.apache.ojb.tutorials;
  
  import org.odmg.DList;
  import org.odmg.Database;
  import org.odmg.Implementation;
  import org.odmg.OQLQuery;
  import org.odmg.Transaction;
  
  import org.apache.ojb.odmg.OJB;
  
  /**
   * ODMG API Usage Examples for the ODMG Tutorial
   *
   * @version
   */
  public class ODMGExample
  {
      public static void storeProduct(Product product)
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
          tx.lock(product, Transaction.WRITE);
          tx.commit();
      }
  
      public static Product findProductByName(String name) throws Exception
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
  
          OQLQuery query = impl.newOQLQuery();
          query.create("select products from " + Product.class + " where name = '" + name
+ "'");
          DList results = (DList) query.execute();
          Product product = (Product) results.iterator().next();
  
          tx.commit();
          return product;
      }
  
      public static void sellProduct(Product product, int number)
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
  
          tx.lock(product, Transaction.WRITE);
          product.setStock(new Integer(product.getStock().intValue() -  number));
  
          tx.commit();
      }
  
      public static void deleteProduct(Product product)
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
          Database db = impl.getDatabase(product);
          db.deletePersistent(product);
          tx.commit();
      }
  
      public static void main(String[] args) throws Exception
      {
          Implementation odmg = OJB.getInstance();
          Database db = odmg.newDatabase();
          db.open("default", Database.OPEN_READ_WRITE);
  
          Product product = new Product();
          product.setName("Widget");
          product.setPrice(new Double(9.99));
          product.setStock(new Integer(11));
  
          storeProduct(product);
  
          Product same = findProductByName(product.getName());
          System.out.println(same.getId() + " = " + product.getId());
          sellProduct(same, 1);
          db.close();
      }
  }
  
  
  
  1.1                  db-ojb/xdocs/odmg-tutorial.xml
  
  Index: odmg-tutorial.xml
  ===================================================================
  <?xml version="1.0"?>
  <!-- @version  -->
  <document>
      <properties>
          <author email="brianm@apache.org">Brian McCallister</author>
          <title>ObJectRelationalBridge Tutorial - ODMG</title>
      </properties>
      <body>
          <section name="The ODMG API">
              <subsection name="Introduction">
                  <p>
                      The ODMG API is an implementation of the <a href="http://www.odmg.org/">ODMG
3.0</a>
                      Object Persistence API. The ODMG API provides a higher-level API and
query
                      language based interface over the <a href="pb-tutorial.html">PersistenceBroker
API</a>.
                  </p>
                  <p>
                      This tutorial operates on a simple example class:
                  </p>
                  <source><![CDATA[
  package org.apache.ojb.tutorials;
  
  public class Product
  {
      /* Instance Properties */
  
      private Double price;
      private Integer stock;
      private String name;
  
      /* artificial property used as primary key */
  
      private Integer id;
  
      /* Getters and Setters */
      ...
  }
                  ]]></source>
                  <p>
                      The metadata descriptor for mapping this class is described in the
                      <a href="mapping-tutorial.html">mapping tutorial</a>
                  </p>
                  <p>
                      The source code for this tutorial is available with the source distribution
                      of OJB in the <code>src/test/org/apache/ojb/tutorials/</code>
directory.
                  </p>
              </subsection>
              <subsection name="Initializing ODMG">
                  <p>
                      The ODMG implementation needs to have a database opened for it to access.
                      This is accomplished via the following code:
                  </p>
                  <source><![CDATA[
  
          Implementation odmg = OJB.getInstance();
          Database db = odmg.newDatabase();
          db.open("default", Database.OPEN_READ_WRITE);
  
          /* ... use the database ... */
  
          db.close();
                  ]]></source>
                  <p>
                      This opens an ODMG <code>Database</code> using the name
specified in
                      metadata for the database -- "default" in this case. Notice the <code>Database</code>
                      is opened in read/write mode. It is possible to open it in read-only
or write-only
                      modes as well.
                  </p>
                  <p>
                      Once a <code>Database</code> has been opened it is available
for use. Unlike
                      <code>PersistenceBroker</code> instances, ODMG <code>Database</code>
instances
                      are threadsafe and can typically be used for the entire lifecycle of
an application.
                      There is no need to call the <code>Database.close()</code>
method until the database
                      is truly no longer needed.
                  </p>
              </subsection>
              <subsection name="Persisting New Objects">
                  <p>
                      Persisting an object via the ODMG API is handled by writing it to the
peristence
                      store within the context of a transaction:
                  </p>
                  <source><![CDATA[
      public static void storeProduct(Product product)
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
          tx.lock(product, Transaction.WRITE);
          tx.commit();
      }
                  ]]></source>
                  <p>
                      The <code>OJB.getInstance()</code> function provides the
ODMG <code>Implementation</code>
                      instance required for using the ODMG API. From here on out it is straight
ODMG
                      code that should work against any compliant ODMG implementation.
                  </p>
                  <p>
                      Once the ODMG implementation has been obtained it is used to begin a
transaction,
                      obtain a write lock on the <code>Product</code>, and commit
the transaction. It is
                      very important to note that all changes need to be made within transactions
in the
                      ODMG API. When the transaction is committed the changes are made to
the database. Until
                      the transaction is committed the database is unaware of any changes
-- they exist
                      solely in the object model.
                  </p>
              </subsection>
              <subsection name="Querying Persistent Objects">
                  <p>
                      The ODMG API uses the OQL query language for obtaining references to
persistent objects.
                      OQL is very similar to SQL, and using it is very similar to use JDBC.
The ODMG
                      implementation is used to create a query, the query is specifed, executed,
and a
                      list fo results is returned:
                  </p>
                  <source><![CDATA[
      public static Product findProductByName(String name) throws Exception
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
  
          OQLQuery query = impl.newOQLQuery();
          query.create("select products from " + Product.class + " where name = '" + name
+ "'");
          DList results = (DList) query.execute();
          Product product = (Product) results.iterator().next();
  
          tx.commit();
          return product;
      }
                  ]]></source>
              </subsection>
              <subsection name="Updating Persistent Objects">
                  <p>
                      Updating a persistent object is done by modifying it in the context
of a transaction,
                      and then committing the transaction:
                  </p>
                  <source><![CDATA[
      public static void sellProduct(Product product, int number)
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
  
          tx.lock(product, Transaction.WRITE);
  
          product.setStock(new Integer(product.getStock().intValue() -  number));
  
          tx.commit();
      }
                  ]]></source>
                  <p>
                      The sample code obtains a write lock on the object, binding it to the
transaction,
                      changes the object, and commits the transaction. The newly modified
<code>Product</code>
                      now has a new <code>stock</code> value.
                  </p>
              </subsection>
              <subsection name="Deleting Persistent Objects">
                  <p>
                      Deleting persistent objects requires directly addressing the <code>Database</code>
which
                      contains the persistent object. This can be obtained from the ODMG
                      <code>Implementation</code> by asking for it. Once retrieved,
just ask the
                      <code>Database</code> to delete the object. Once again,
this is all done in the context
                      of a transaction.
                  </p>
                  <source><![CDATA[
      public static void deleteProduct(Product product)
      {
          Implementation impl = OJB.getInstance();
          Transaction tx = impl.newTransaction();
  
          Database db = impl.getDatabase(product);
          db.deletePersistent(product);
  
          tx.commit();
      }
                  ]]></source>
                  <p>
                      It is important to note that the <code>Database.deletePerstient()</code>
call does
                      not delete the object itself, just the persistent representation of
it. The transient
                      object still exists and can be used however desired -- it is simply
no longer
                      persistent.
                  </p>
              </subsection>
          </section>
          <section name="Notes on Using the ODMG API">
              <subsection name="Transactions">
                  <p>
                      The ODMG API uses object-level transactions, compared to the PersistenceBroker
                      database-level transactions. An ODMG <code>Transaction</code>
instance contains
                      all of the changes made to the object model within the context of that
                      transaction, and will not commit them to the database until the ODMG
                      <code>Transaction</code> is committed. At that point it
will use a database
                      transaction to ensure atomicity of its changes.
                  </p>
              </subsection>
              <subsection name="Locks">
                  <p>
                      The ODMG specification includes several levels of locks and isolation.
These are
                      explained in much more detail in the <a href="lockmanager.html">Lock
Manager</a>
                      documentation.
                  </p>
              </subsection>
          </section>
      </body>
  </document>
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org


Mime
View raw message