You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by ar...@apache.org on 2003/08/28 21:35:31 UTC
cvs commit: db-ojb/xdocs mapping-tutorial.xml pb-tutorial.xml
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