db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject cvs commit: db-ojb/xdocs mapping-tutorial.xml pb-tutorial.xml
Date Thu, 28 Aug 2003 19:35:31 GMT
arminw      2003/08/28 12:35:31

  Modified:    xdocs    pb-tutorial.xml
  Added:       xdocs    mapping-tutorial.xml
  Log:
  add new/updated docu by Brain McCallister
  
  Revision  Changes    Path
  1.2       +4 -4      db-ojb/xdocs/pb-tutorial.xml
  
  Index: pb-tutorial.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/pb-tutorial.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- pb-tutorial.xml	19 Aug 2003 15:35:57 -0000	1.1
  +++ pb-tutorial.xml	28 Aug 2003 19:35:31 -0000	1.2
  @@ -30,7 +30,7 @@
   
       private Double price;
       private Integer stock;
  -    private String name;
  +    private String name;lean
   
       /* artificial property used as primary key */
   
  @@ -42,7 +42,7 @@
                   ]]></source>
                   <p>
                       The metadata descriptor for mapping this class is described in the
  -                    XXXmetadata tutorialXXX.
  +                    <a href="mapping-tutorial.html">mapping tutorial</a>
                   </p>
                   <p>
                       The source code for this tutorial is available with the source distribution
  @@ -353,7 +353,7 @@
                       Additionally, the closing of <code>PersistenceBroker</code>
instances is best
                       handled in <code>finally</code> blocks in order to guarantee
that it is run,
                       even if an exception occurs. If the <code>PersistenceBroker.close()</code>
is not
  -                    called then the application will lean broker instances. The best way
to ensure that
  +                    called then the application will leak broker instances. The best way
to ensure that
                       it is always called is to always retrieve and use <code>PersistenceBroker</code>
                       instances within a <code>try {...}</code> block, and always
close the broker
                       in a <code>finally {...}</code> block attached to the <code>try
{...}</code> block.
  
  
  
  1.1                  db-ojb/xdocs/mapping-tutorial.xml
  
  Index: mapping-tutorial.xml
  ===================================================================
  <?xml version="1.0"?>
  <!-- @version $Id: mapping-tutorial.xml,v 1.1 2003/08/28 19:35:31 arminw Exp $ -->
  <document>
      <properties>
          <author email="brian@skife.org">Brian McCallister</author>
          <title>ObJectRelationalBridge Tutorial - O/R Mapping Metadata</title>
      </properties>
      <body>
          <section name="What is the Object-Relational Mapping Metadata?">
              <p>
                  The O/R mapping metadata is the specific configuration information that
specifies
                  how to map classes to relational tables. In OJB this is primarily accomplished
                  through an xml document, the <code>repository.xml</code> file,
which contains
                  all of the initial mapping information.
              </p>
              <subsection name="The Product Class">
                  <p>
                     This tutorial looks at mapping a simple class with no relations:
                  </p>
                  <source><![CDATA[
  package org.apache.ojb.tutorials;
  
  public class Product
  {
      /** price per item*/
      private Double price;
  
      /** stock of currently available items*/
      private Integer stock;
  
      /** product name*/
      private String name;
  
      /* Getters and Setters not shown for tutorial */
  }
                  ]]></source>
                  <p>
                      This class has three fields, <code>price, stock,</code>
and <code>name</code>,
                      that need to be mapped to the database. Additionally, we will introduce
one
                      artificial field used by the database that has no real meaning to the
class, an
                      artificial key primary id:
                  </p>
                  <source><![CDATA[
      /** Artificial primary-key */
      private Integer id;
                  ]]></source>
                  <p>
                      Including the primary-key attribute in the class definition is optional,
                      <a href="howto-use-anonymous-keys.html">anonymous keys</a>
                      can also be used to keep this database artifact hidden in the database.
However,
                      as access to an artifical unique identifier for a particular object
instance can be
                      useful, particularly in web-based applications, this tutorial will expose
it.
                  </p>
              </subsection>
              <subsection name="The Database">
                  <p>
                      OJB is very flexible in terms of how it can map classes to database
tables, however
                      the simplest technique for mapping a single class to a relational database
is to
                      map the class to a single table, and each attribute on the class to
a single
                      column. Each row will then represent a unique instance of that class.
                  </p>
                  <p>
                      The DDL for such a table, for the <code>Product</code> class
might look like:
                  </p>
                  <source><![CDATA[
  CREATE TABLE product
  (
      id INTEGER PRIMARY KEY,
      name VARCHAR(100),
      stock INTEGER,
      price DOUBLE
  )
                  ]]></source>
                  <p>
                      The individual field names in the database and class definition match
here,
                      but this is no requirement. They may vary independently of each other
as the
                      metadata will specify what maps to what.
                  </p>
              </subsection>
              <subsection name="The Metadata">
                  <p>
                      The <code>repository.xml</code> document is split into several
physical documents.
                      The <code>repository_user.xml</code> xml file is used to
contain user-defined
                      mappings. OJB uses the other ones for managing other metadata, such
as database
                      information.
                  </p>
                  <p>
                      In general each class will be defined within a <code>class-descriptor</code>
element
                      with <code>field-descriptoy</code> child elements for each
field. In addition
                      the mapping of references and collections is described in the
                      <a href="tutorial3.html">Advanced O/R Tutorial</a>. This
tutorial sticks
                      to mapping a single, simplistic, class.
                  </p>
                  <p>
                      The complete mapping for the <code>Product</code> class
is as follows:
                  </p>
                  <source><![CDATA[
     <class-descriptor
     	  class="org.apache.ojb.tutorials.Product"
     	  table="PRODUCT"
     >
        <field-descriptor
           name="id"
           column="ID"
           jdbc-type="INTEGER"
           primarykey="true"
           autoincrement="true"
        />
        <field-descriptor
           name="name"
           column="NAME"
           jdbc-type="VARCHAR"
        />
        <field-descriptor
           name="price"
           column="PRICE"
           jdbc-type="DOUBLE"
        />
        <field-descriptor
           name="stock"
           column="STOCK"
           jdbc-type="INTEGER"
        />
     </class-descriptor>
                  ]]></source>
                  <p>
                      Examine the <code>class-descriptor</code> element. It has
two attributes:
                  </p>
                  <ol>
                      <li>
                          class - This attribute is used to specify the fully-qualified Java
                          class name for this mapping.
                      </li>
                      <li>
                          table - This attribute specifies which table is used to store instances
                          of this class.
                      </li>
                  </ol>
                  <p>
                      Other information can be specified here, such as proxies
                      and custom row-readers as specified in the <a href="repository.html#class-descriptor">
                      repository.xml documentation</a>.
                  </p>
                  <p>
                      Examine now the first <code>field-descriptor</code> element.
This is used to
                      describe the <code>id</code> field of the <code>Product</code>
class. Several
                      required attributes are specified:
                  </p>
                  <ol>
                      <li>
                          name - This specifies the name of the instance variable in the
                          Java class.
                      </li>
                      <li>
                          column - This specifies the column in the table specified for this
                          class used to store the value.
                      </li>
                      <li>
                          jdbc-type - This attribute is determined by the OJB-JDBC mapping
                          information detailed in the <a href="jdbc-types.html">JDBC
Types</a>
                          documentation. Custom mappings are possible, as described in the
                          JDBC Types documentation, so it is necesary
                          to specify this - it cannot be infered from the Java type.
                      </li>
                  </ol>
                  <p>
                      In addition to those required attributes, notice that the first element
                      specifies two optional attributes:
                  </p>
                  <ol>
                      <li>
                          primary-key - This attribute specifies that this field is the primary
key
                          for this class.
                      </li>
                      <li>
                          autoincrement - The <code>autoincrement</code> attribute
specifies that the
                          value will be automatically assigned by OJB <a href="sequencemanager.html">
                          sequence manager</a>. This might use a database supplied sequence,
or, by
                          default, an OJB generated value.
                      </li>
                  </ol>
                  <p>
                      Each <code>field-descriptor</code> must define the <code>name,
column</code>,
                      and <code>jdbc-type</code> attributes.
                  </p>
              </subsection>
          </section>
          <section name="Advanced Topics">
              <subsection name="Relations">
                  <p>
                      As most object models have relationships between objects, mapping specific
                      types of relationships (1:1, 1:Many, Many:Many) is important in mapping
                      objects into a relational database. The
                      <a href="tutorial3.html">Advanced O/R Mapping Tutorial</a>
                      discusses this in great detail.
                  </p>
                  <p>
                      It is important to note that this metadata mapping can be modified at
runtime
                      through the <a href="api/org/apache/ojb/broker/metadata/MetadataManager.html">
                      <code>org.apache.ojb.metadata.MetadataManager</code></a>
class.
                  </p>
              </subsection>
              <subsection name="Anonymous Keys">
                  <p>
                      This tutorial uses explicit keys mapped into the Java class. It is also
                      possible to keep artificial keys completely hidden within the database.
                      The <a href="howto-use-anonymous-keys.html">Anonymous Keys HOWTO</a>
                      explains how this is accomplished.
                  </p>
              </subsection>
              <subsection name="Large Projects">
                  <p>
                      Projects with small numbers of persistent classes can be mapped by hand,
                      however, many projects can have hundreds, or even thousands, of
                      distinct classes which must be mapped. In these circumstances managing
                      the class-database mapping by hand is not viable. The
                      <a href="howto-build-mappings.html">How To Build Mappings HOWTO</a>
                      explores different tools which can be used for managing large-scale
                      mapping.
                  </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