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 2007/10/03 00:20:33 UTC
svn commit: r581418 [1/2] - in
/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs:
./ docu/ docu/guides/ docu/howtos/ docu/tutorials/
Author: arminw
Date: Tue Oct 2 15:20:30 2007
New Revision: 581418
URL: http://svn.apache.org/viewvc?rev=581418&view=rev
Log:
update documentation
Modified:
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/howtos/howto-use-lobs.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/features.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/tabs.xml
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml Tue Oct 2 15:20:30 2007
@@ -39,14 +39,12 @@
</p>
<ul>
<li>It's fully ODMG 3.0 compliant</li>
- <li>It will have a full JDO implementation</li>
- <li>It's higly scalable (Loadbalanced Multiserver scenario)</li>
+ <li>It's higly scalable</li>
<li>It provides multiple APIs:
<ul>
<li>The full fledged ODMG-API,</li>
- <li>The JDO API (planned) </li>
<li>
- and the PersistenceBroker API. This API provides a O/R persistence
+ The PersistenceBroker API. This API provides a O/R persistence
kernel which can be used to build higher level APIs (like the ODMG and
JDO Implementations)
</li>
@@ -54,22 +52,17 @@
</li>
<li>It's able to handle multiple RDBMS simultaneously.</li>
<li>
- it has a slick MetaLevel Architecture: By changing the MetaData at runtime
+ it has a slick meta-level Architecture: By changing the MetaData at runtime
you can change the O/R mapping behaviour. (E.G. turning on/off usage of
Proxies.)
</li>
<li>
- It has a simple CacheMechanisms that is fully garbage collectable by usage
- of weak references.
- </li>
- <li>It has a simple and clean pattern based design.</li>
- <li>
It uses a configurable plugin concept. This allows to replace components
- (e.g. the ObjectCache) by user defined Replacements.
+ (e.g. the ObjectCache) by user defined replacements.
</li>
<li>
- It has a modular architecture (you can quite easily reuse some components
- in your own applications if you don't want to use the whole thing:
+ It has a modular architecture (you can quite easily reuse some components
+ in your own applications if you don't want to use the whole thing:
<ul>
<li>The PersistenceBroker (e.g. to build your own PersistenceManager)</li>
<li>The Query Interface as an abstract query syntax</li>
@@ -84,7 +77,10 @@
</li>
</ul>
<p>
- Before making OJB an OpenSource project I had a look around at the
+ A more complete feature list can be found <a href="site:features">here</a>.
+ </p>
+ <p>
+ Before making OJB an OpenSource project (about 2000/2001) I had a look around at the
emerging OpenSource O/R scene and was asking myself if there is
really a need for yet another O/R tool.
I came to the conclusion that there was a need for OJB because:
@@ -548,8 +544,9 @@
too many concurrent threads exhaust the connection pool.
</li>
<li>
- of a <em>PersistenceBroker</em> leak (How to automatically
- <a href="site:pb-guide/detect-leak">detect broker leaks</a>).
+ of a <code>PersistenceBroker</code> <em>leak</em>. The mandatory
+ <code>PersistenceBroker.close()</code> call (after use) is missed. How to automatically
+ detect leaks can be found in the <a href="site:pb-guide/detect-leak">persistence broker guide</a>.
</li>
</ul>
</answer>
@@ -650,7 +647,7 @@
<br/>
The PB instance has no object state detection, thus it update all
specified objects. So the unchanged object O will be updated and
- dependend on the used <a href="site:basic-technique/cascading">reference settings</a>
+ dependend on the used <a href="site:basic-technique/manage-references">reference settings</a>
(cascading update enabled or not) the remaining objects a,b,c be updated too.
Again dependend on the used settings
(<a href="site:advanced-technique/which-collection-type">collection types</a>)
@@ -1074,6 +1071,33 @@
</faq>
+ <faq id="cascadingDelete">
+ <question>
+ Enable cascading delete?
+ </question>
+ <answer>
+ <p>
+ Cascading delete of referenced/linked objects is supported by OJB and can be
+ enabled using the attribute
+ <a href="site:basic-technique/manage-references"><code>auto-delete</code></a>.
+ </p>
+ </answer>
+ </faq>
+
+
+ <faq id="deleteOrphan">
+ <question>
+ Enable OJB to delete orphan objects (removed from collections)?
+ </question>
+ <answer>
+ <p>
+ OJB supports the automatic delete of
+ <a href="site:basic-technique/delete-orphan">orphan/removed collections objects</a>.
+ </p>
+ </answer>
+ </faq>
+
+
<faq id="itOrCol">
<question>
Difference between getIteratorByQuery() and getCollectionByQuery()?
@@ -1197,7 +1221,7 @@
<answer>
<p>
Please refer to
- <a href="site:repository/batch-mode">batch-mode attribute section of jdbc-connection-descriptor in repository guide</a>.
+ <a href="site:connection/batch">the connection handling guide</a>.
</p>
</answer>
</faq>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml Tue Oct 2 15:20:30 2007
@@ -224,7 +224,8 @@
</section>
-
+
+ <anchor id="inheritance"/>
<section>
<title>Mapping Inheritance Hierarchies</title>
<p>
@@ -243,8 +244,7 @@
<img src="images/mapping_inheritance_example.png" alt="mapping-inheritance.png"/>
</p>
<p>
- If we have to define database tables that have to contain these classes
- we have to choose one of the following solutions:
+ To map this class hierarchy to database tables we can choose one of the following solutions:
</p>
<ol>
<li>
@@ -269,8 +269,10 @@
<p>
OJB provides direct support for all three approaches.
</p>
- <note>But it's currently not recommended to mix mapping strategies
- within the same hierarchy !</note>
+ <note>
+ But it's currently not recommended to mix mapping strategies
+ within the same hierarchy !
+ </note>
<p>
In the following we demonstrate how these mapping
approaches can be implemented by using OJB.
@@ -279,7 +281,7 @@
<anchor id="table-per-class"/>
<section>
- <title>Mapping Each Class of a Hierarchy to a Distinct Table (table per class)</title>
+ <title>Mapping Each Class of a Hierarchy to a Table (table per class)</title>
<p>
This is the most simple solution. Just write a complete
<a href="site:repository/class-descriptor">ClassDescriptor</a> with
@@ -301,7 +303,7 @@
{
}
....
-// getter/setter for id and ojbConcreteClass
+// getter/setter for id and name
}
public class Executive extends Employee
@@ -432,7 +434,7 @@
</p>
<p>
Storing <code>Employee, Executive</code> and <code>Manager</code> objects to this table
- works fine. But now consider a Query against the baseclass <code>Employee</code>.
+ works fine. But now consider a query against the base class <code>Employee</code>.
How can the correct type of the stored objects be determined?
</p>
<p>
@@ -640,24 +642,14 @@
Class ojbConcreteClass = (Class) row.get(OJB_CONCRETE_CLASS_KEY);
if(ojbConcreteClass != null)
{
- result = m_cld.getRepository().getDescriptorFor(ojbConcreteClass);
- // if we can't find class-descriptor for concrete
- // class, something wrong with mapping
- if (result == null)
- {
- throw new PersistenceBrokerException(
- "Can't find class-descriptor for ojbConcreteClass '"
- + ojbConcreteClass + "', the main class was "
- + m_cld.getClassNameOfObject());
- }
- }
+ ...
+
return result;
}]]></source>
<p>
After implementing your own <a href="#using-rowreader"><code>RowReader</code></a>
- you must edit the ClassDescriptor for
- the respective class in the XML repository to specify the usage of
- your RowReader Implementation:
+ you must edit the ClassDescriptor for the respective class in the XML repository to
+ specify the usage of your specific RowReader implementation:
</p>
<source><![CDATA[
<class-descriptor
@@ -669,7 +661,8 @@
>
...]]></source>
<p>
- You will learn more about RowReaders in <a href="#using-rowreader">this section.</a>
+ It's also possible to replace OJB's default RowReader implementation in general - you will
+ learn more about RowReaders in <a href="#using-rowreader">this section.</a>
</p>
</section>
</section>
@@ -786,7 +779,7 @@
foreign key reference.
</p>
<note>
- 1. The <a href="site:basic-technique/cascading"><em>auto-xxx</em> attributes</a> and the
+ 1. The <a href="site:basic-technique/manage-references"><em>auto-xxx</em> attributes</a> and the
<a href="site:basic-technique/reference-proxy"><em>proxy</em> attribute</a>
will be ignored when using the <em>super</em> keyword.
<br/>
@@ -1719,7 +1712,7 @@
<anchor id="manageable-collection"/>
<section>
- <title>Manageable Collection</title>
+ <title>Manageable Collection / Delete orphan</title>
<p>
In <a href="site:basic-technique/one-to-n">1:n</a> or
<a href="site:basic-technique/m-to-n">m:n</a> relations, OJB can handle
@@ -1780,7 +1773,7 @@
<title>Types Allowed for Implementing 1:n and m:n Associations</title>
<p>
By default OJB use the collection implementation classes specified in the
- <a href="ext:ojb.properties">OJB.properties</a> file. But it's also possible to
+ <a href="#default-collection-types">OJB.properties</a> file. But it's also possible to
define specific classes for each <code>collection-descriptor</code>. See attribute
<a href="site:repository/collection-descriptor">collection-descriptor.collection-class</a>
for more information.
@@ -1878,12 +1871,12 @@
was introduced. Now we talk about which type to use.
</p>
<p>
- By default OJB use:
+ <a href="#default-collection-types">By default OJB use</a>:
</p>
<ul>
<li>
- a <em>removal-aware</em> collection implementations for
- <a href="site:basic-technique/one-to-n">1:n relations</a>
+ a <em>removal-aware</em> collection implementations (to automatically delete orphan
+ collection objects) for <a href="site:basic-technique/one-to-n">1:n relations</a>
</li>
<li>
normal manageable collection implementations for
@@ -1892,12 +1885,14 @@
</ul>
<p>
Removal aware implementations (classes prefixed with <em>Removal...</em>) track
- removal of elements. This tracking allow the <code>PersistenceBroker</code>
+ removal of elements - to enable automatic delete of orphan collection objects.
+ This tracking allow the <code>PersistenceBroker</code>
to <strong>delete elements</strong> from the database that have been
removed from the collection before a <code>PB.store()</code> operation occurs.
</p>
<p>
- Using removal aware is <strong>undesired</strong> in some cases:
+ Using removal aware collections (enabling delete of orphan collection objects)
+ is <strong>undesired</strong> in some cases:
</p>
<ul>
<li>
@@ -1976,7 +1971,7 @@
<code>ManageableCollection</code> implementation which supports <code>java.util.Collection</code>
and furthermore tracks removal of elements. This tracking allow the <code>PersistenceBroker</code>
to delete elements that have been removed from the collection even if no <code>Persistencebroker.delete</code>
- call was performed the removed objects. This will allow to use the <a href="site:pb-guide">PB api</a>
+ call was performed for removed objects. This will allow to use the <a href="site:pb-guide">PB api</a>
in a way pretty close to higher level API's with collection references state detection
e.g. like the <a href="site:odmg-guide">ODMG API</a>.
</td>
@@ -2038,6 +2033,50 @@
>
<inverse-foreignkey field-ref="productGroupId"/>
</collection-descriptor>]]></source>
+ </section>
+
+ <anchor id="default-collection-types"/>
+ <section>
+ <title>Default collection type settings in OJB.properties file</title>
+ <p>
+ By default OJB use the collection implementation classes specified in the
+ <a href="ext:ojb.properties">OJB.properties</a> file. But it's also possible to
+ override the default collection types with specific classes for each
+ <code>collection-descriptor</code> using attribute
+ <a href="site:repository/collection-descriptor"><em>collection-class</em></a>.
+ for more information.
+ </p>
+ <source><![CDATA[
+#----------------------------------------------------------------------------------------
+# ManageableCollection default settings
+#----------------------------------------------------------------------------------------
+# OJB use specific collection class implementations to provide 1:n and m:n references.
+# It's also possible to define specific collection classes for each defined 1:n or m:n
+# reference - please see documentation (repository mapping docs).
+#
+# Default collection classes for 1:n references
+CollectionTypes.OneToManyArray=org.apache.ojb.broker.util.collections.RemovalAwareCollection
+CollectionTypes.OneToManyCollection=org.apache.ojb.broker.util.collections.RemovalAwareCollection
+CollectionTypes.OneToManyList=org.apache.ojb.broker.util.collections.RemovalAwareList
+CollectionTypes.OneToManyVector=org.apache.ojb.broker.util.collections.RemovalAwareVector
+CollectionTypes.OneToManySet=org.apache.ojb.broker.util.collections.RemovalAwareSet
+#
+# Default collection classes for m:n references (never use a removal aware collection
+# implementation for m:n relation)
+CollectionTypes.ManyToManyArray=org.apache.ojb.broker.util.collections.ManageableArrayList
+CollectionTypes.ManyToManyCollection=org.apache.ojb.broker.util.collections.ManageableArrayList
+CollectionTypes.ManyToManyList=org.apache.ojb.broker.util.collections.ManageableArrayList
+CollectionTypes.ManyToManyVector=org.apache.ojb.broker.util.collections.ManageableVector
+CollectionTypes.ManyToManySet=org.apache.ojb.broker.util.collections.ManageableHashSet
+#
+# The Query/OQLQuery entries define the collection types returned
+# from Criteria-based queries/OQL-queries. By default this value is set to a List.
+# This will be good for most situations. If you need the additional features replace
+# the implementation.
+# Default collection classes query results
+CollectionTypes.Query=org.apache.ojb.broker.util.collections.ManageableArrayList
+CollectionTypes.OQLQuery=org.apache.ojb.broker.util.collections.ManageableArrayList
+ ]]></source>
</section>
</section>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml Tue Oct 2 15:20:30 2007
@@ -289,7 +289,7 @@
<code>auto-xxx</code> and
<code>proxy</code> attributes can be
found
- <a href="#cascading">here</a>
+ <a href="#manage-references">here</a>
</p>
<p>
@@ -322,6 +322,15 @@
will be nullified. (On insert it is allowed to set the FK without populating the referenced object)
</li>
<li>
+ <strong>create</strong> On updating or inserting of the main object with
+ <code>PersistenceBroker.store(...)</code>,
+ the referenced object will be:
+ <br/>
+ - stored if it's <a href="#persistence-checker">new (not persistent)</a>
+ <br/>
+ - <a href="#linking"><em>linked</em></a> if it's a persistent object.
+ </li>
+ <li>
<strong>object</strong> On updating or inserting of the main object with
<code>PersistenceBroker.store(...)</code>,
the referenced object will be stored first, then OJB does the same as in
@@ -526,7 +535,7 @@
<em>auto-xxx</em> and
<em>proxy</em> attributes can be
found
- <a href="#cascading">here</a>.
+ <a href="#manage-references">here</a>.
</p>
<p>
@@ -559,6 +568,14 @@
<em>updated</em>, but the referenced objects will be linked automatically (FK assignment) the main object.
</li>
<li>
+ <strong>create</strong> On updating or inserting of the main object with
+ <code>PersistenceBroker.store(...)</code>:
+ <br/>
+ - a referenced object will be stored if it's <a href="#persistence-checker">new (not persistent)</a>
+ <br/>
+ - a referenced object will be <a href="#linking"><em>linked</em></a> if it's a persistent object.
+ </li>
+ <li>
<strong>object</strong> On updating or inserting of the main object with
<code>PersistenceBroker.store(...)</code>,
the referenced objects will be linked and stored automatically.
@@ -617,9 +634,10 @@
<section>
<title>Mapping m:n associations</title>
<p>
- OJB provides support for manually decomposed m:n associations as
- well as an automated support for non decomposed m:n associations.
+ OJB provides support for <a href="#m-to-n-decomposed">manually decomposed m:n associations</a> as
+ well as an automated support for <a href="#m-to-n-undecomposed">non decomposed m:n associations</a>.
</p>
+ <anchor id="m-to-n-decomposed"/>
<section>
<title>Manual decomposition into two 1:n associations</title>
<p>
@@ -803,47 +821,34 @@
</class-descriptor>]]></source>
</section>
+
+ <anchor id="m-to-n-undecomposed"/>
<section>
<title>Support for Non-Decomposed m:n Mappings</title>
<p>
- If there is no need for an association class at the
- object level (we are not interested in role information), OJB can be
- configured to do the m:n mapping transparently.
- For example, a Person does not
- have a collection of
- <code>Role</code> objects but only a Collection of
- <code>Project</code> objects (held in the
- attribute
- <code>projects</code>).
- Projects also are expected to contain a collection of
- <code>Person</code> objects
- (hold in attribute
- <code>persons</code>).
- </p>
- <p>
- To tell OJB how to handle this m:n association the
- CollectionDescriptors for the Collection attributes
- <code>projects</code>
- and
- <code>roles</code> need additional
- information on the intermediary table and the foreign key columns
- pointing to the
- <code>PERSON</code> table
- and the foreign key columns pointing to the
- <code>PROJECT</code>
- table:
+ If there is no need for an association class at the object level (we are not interested in
+ role information), OJB can be configured to do the <em>m:n mapping</em> transparently. For
+ example, a <code>Person</code> does not have a collection of <code>Role</code> objects but only a
+ collection of <code>Project</code> objects (held in the attribute <code>projects</code>).
+ Projects also are expected to contain a collection of <code>Person</code> objects (hold in
+ attribute <code>persons</code>).
+ </p>
+ <p>
+ To tell OJB how to handle this m:n association the CollectionDescriptors for the Collection
+ attributes <code>projects</code> and <code>roles</code> need additional
+ information on the intermediary table (called <em>indirection table</em>) and the foreign
+ key columns pointing to the <code>PERSON</code> table and the foreign key columns pointing
+ to the <code>PROJECT</code> table:
</p>
<note>
OJB supports a
<a href="site:advanced-technique/manageable-collection">multiplicity of collection implementations</a>,
inter alia <code>org.apache.ojb.broker.util.collections.RemovalAwareCollection</code>
- and
- <code>org.apache.ojb.broker.util.collections.RemovalAwareList</code>. By default the
+ and <code>org.apache.ojb.broker.util.collections.RemovalAwareList</code>. By default the
removal aware collections were used. This cause problems in m:n relations when
- <code>auto-update="true" or "object"</code> and
- <code>auto-delete="false" or "none"</code> is set, because objects
- deleted in the collection will be deleted on update of main object. Thus it is recommended to
- use a NOT removal aware collection class in m:n relations using the
+ <code>auto-update="true" or "object"</code> and <code>auto-delete="false" or "none"</code>
+ is set, because objects deleted in the collection will be deleted on update of main object.
+ Thus it is recommended to use a NOT removal aware collection class in m:n relations using the
<a href="site:repository/collection-descriptor">collection-class</a> attribute.
</note>
<p>
@@ -882,7 +887,7 @@
collection-class="org.apache.ojb.broker.util.collections.ManageableArrayList"
element-class-ref="org.apache.ojb.broker.Project"
auto-retrieve="true"
- auto-update="true"
+ auto-update="create"
indirection-table="PERSON_PROJECT"
>
<fk-pointing-to-this-class column="PERSON_ID"/>
@@ -918,7 +923,7 @@
collection-class="org.apache.ojb.broker.util.collections.ManageableArrayList"
element-class-ref="org.apache.ojb.broker.Person"
auto-retrieve="true"
- auto-update="false"
+ auto-update="create"
indirection-table="PERSON_PROJECT"
>
<fk-pointing-to-this-class column="PROJECT_ID"/>
@@ -928,7 +933,7 @@
<p>
That is all that needs to be configured! See the code in class
<code>org.apache.ojb.broker.MtoNMapping</code>
- for JUnit testmethods using the classes
+ for JUnit test methods using the classes
<code>Person</code>,
<code>Project</code> and
<code>Role</code>.
@@ -947,7 +952,7 @@
<code>auto-xxx</code> and
<code>proxy</code> attributes can be
found
- <a href="#cascading">here</a>
+ <a href="#manage-references">here</a>
</p>
<p>
@@ -986,6 +991,14 @@
</note>
<ul>
<li>
+ <strong>create</strong> On updating or inserting of the main object with
+ <code>PersistenceBroker.store(...)</code>:
+ <br/>
+ - a referenced object will be stored if it's <a href="#persistence-checker">new (not persistent)</a>
+ <br/>
+ - a referenced object will be <a href="#linking"><em>linked</em></a> if it's a persistent object.
+ </li>
+ <li>
<strong>object</strong> On updating or inserting of the main object with
<code>PersistenceBroker.store(...)</code>,
the referenced objects will be linked and stored automatically.
@@ -1042,9 +1055,9 @@
</section>
- <anchor id="cascading"/>
+ <anchor id="manage-references"/>
<section>
- <title>Setting Load, Update, and Delete Cascading</title>
+ <title>Load, Update and cascading delete of referenced objects</title>
<p>
As shown in the sections on 1:1, 1:n and m:n mappings, OJB manages
associations (or object references in Java terminology) by declaring
@@ -1066,6 +1079,7 @@
<em>auto-update</em> - possible settings are
<em>none</em>,
<em>link</em>,
+ <em>create</em>,
<em>object</em> and deprecated
[
<em>false</em>,
@@ -1084,8 +1098,8 @@
</li>
</ul>
<warning>
- When using a top-level api (ODMG, OTM, JDO) it is <strong>mandatory to use specific
- auto-xxx settings</strong>.<br/>
+ When using a top-level api (ODMG, OTM, JDO) it's possible that <strong>specific
+ auto-xxx settings are mandatory</strong>.<br/>
<br/>For <em>OTM-</em> and <em>JDO-api</em> the settings are:
<br/>- <em>auto-retrieve="true"</em>
<br/>- <em>auto-update="false"</em>
@@ -1093,7 +1107,7 @@
<br/>This are at the same time the <em>default</em> auto-XXX settings (so don't
specify any of this attributes will have the same effect).
<br/>
- <br/>For the <em>ODMG-api</em> the mandatory settings can be found in the
+ <br/>For the <em>ODMG-api</em> the mandatory/supported settings can be found in the
<a href="site:odmg-guide/metadata">odmg-guide</a>.
</warning>
<p>
@@ -1135,7 +1149,7 @@
<br/>
Before you can perform an update
on the main object, you have to "retrieve" the 1:1 reference. Otherwise you will end up with an nullified
- reference enty in main object, because OJB doesn't find the referenced object on update and
+ reference entry in main object, because OJB doesn't find the referenced object on update and
assume the reference was removed.
</note>
<ul>
@@ -1295,9 +1309,29 @@
</section>
+ <anchor id="delete-orphan"/>
+ <section>
+ <title>Delete or Unlink of orphan collection objects</title>
+ <p>## TODO: IS NOT UP-TO-DATE ##</p>
+ <p>
+ OJB support several possibilities of handling objects removed from
+ referenced/linked 1:n or m:n collections (so called <em>orphan (collection) objects</em>):
+ <br/>
+ - Do nothing with the removed object when the main object is stored<br/>
+ - Unlink the removed object when the main object is stored<br/>
+ - Delete the removed object when the main object is stored
+ <br/>
+ <a href="site:odmg-guide/metadata">specific odmg-api settings</a>
+ </p>
+ <p>
+ If the PB-API is used
+ </p>
+ </section>
+
+
<anchor id="using-proxy"/>
<section>
- <title>Lazy Loading via Proxy Classes</title>
+ <title>Lazy Loading (via Proxy Classes)</title>
<p>
Proxy classes can be used for "lazy loading" aka "lazy
materialization". Using Proxy classes can help you in reducing
@@ -1339,7 +1373,8 @@
</li>
<li>
<p>
- <em>Use proxies for the referenced objects</em> - the collection is filled
+ <em>Use proxies for the referenced object class</em> - <code>Article</code>,
+ the collection is filled
with fifteen proxy objects, that contain only an OID and a void reference.
The fifteen <code>Article</code> objects are not instantiated when the
<code>ProductGroup</code> is initially materialized.
@@ -1348,7 +1383,7 @@
object will it load its "real subject" and delegate the
method call to it. Using this dynamic delegation mechanism
instantiation of persistent objects and database lookups can be
- minimized.
+ minimized. More details see <a href="#dynamic-proxy">dynamic proxy</a>.
</p>
</li>
<li>
@@ -1358,7 +1393,8 @@
proxy object and fully materialized on the first reference access.
<br/>
This is the recommended way (in most cases) to realize lazy
- loading for references (1:1, 1:n and m:n).
+ loading for references (1:1, 1:n and m:n). More details see
+ <a href="#reference-proxy">dynamic proxy</a>.
</p>
</li>
</ul>
@@ -2044,7 +2080,7 @@
Same behavier as <code>PersistenceCheckerSolidImpl</code> but the persistence storage
roundup is disbaled and will never be performed.
<note>
- This implementation is only recommended when OJB manage the id-generation via
+ This implementation is only recommended if OJB manage the id-generation via
<a href="site:sequence-manager">sequence manager</a> and deleted objects only
re-added with nullified primary key fields.
</note>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml Tue Oct 2 15:20:30 2007
@@ -47,8 +47,10 @@
</ul>
</section>
+
<anchor id="connection-factory"/>
- <section><title>ConnectionFactory</title>
+ <section>
+ <title>ConnectionFactory</title>
<p>
The <code>org.apache.ojb.broker.accesslayer.ConnectionFactory</code> interface implementation
is a pluggable component (via the <a href="ext:ojb.properties">OJB.properties</a> file
@@ -324,6 +326,85 @@
<br/>
All other top-level API should behave similar.
</p>
+ </section>
+
+
+ <anchor id="batch"/>
+ <section>
+ <title>How to enable Batch-Statements</title>
+ <p>
+ OJB supports the use of <em>batch statements</em>. This can dramatically
+ improve performance of mass insert/update/delete operations of persistence
+ capable objects (with the same object type).
+ </p>
+ <p>
+ There are to steps to prepare OJB for the use of <em>batch statements</em>:
+ </p>
+ <ul>
+ <li>
+ First step is to activate OJB's batch support in the
+ <a href="site:repository/batch-mode">jdbc-connection-descriptor via <em>batch-mode</em> attribute</a>.
+ </li>
+ <li>
+ Next step is to enable the batch mode of the current used <code>PersistenceBroker</code> instance
+ by setting a batch mode flag in the <code>ConnetionManager</code>:
+ <source><![CDATA[
+persistenceBroker.serviceConnectionManager().setBatchMode(true)]]></source>
+ </li>
+ </ul>
+ <p>
+ Assume we want to persist a bulk of <code>Article</code> objects. The code will look like this:
+ </p>
+ <source><![CDATA[
+Article[] arr = ...
+broker = //lookup PersistenceBroker instance;
+// enable batch support
+broker.serviceConnectionManager().setBatchMode(true);
+broker.beginTransaction();
+for (int i = 0; i < arr.length; i++)
+{
+ broker.store(arr[i], ObjectModification.INSERT);
+}
+broker.commitTransaction();
+ ]]></source>
+
+ <note>
+ Not until method <code>setBatchMode(true)</code> is called (enable OJB's batch support),
+ OJB will use batch statements.
+ The <a href="site:repository/batch-mode"><em>batch-mode</em></a> attribute in the
+ <code>jdbc-connection-descriptor</code> only
+ activate OJB's batch statements support. So it's possible to completely disable the
+ use of batch statements (set <em>batch-mode</em> 'false' in
+ <a href="site:repository">repository file</a>) independent from the
+ <code>setBatchMode(...)</code> calls in the source code.
+ <br/>
+ <br/>
+ On <code>PersistenceBroker.close()</code> call
+ OJB always switches off batch mode, thus you have to call
+ <code>ConnectionManager.setBatchMode(true)</code> on each
+ new obtained PB instance.
+ </note>
+
+ <note>
+ OJB 1.0.4 and earlier:
+ <br/>
+ When using <a href="site:sequence-manager/identity-columns">database identity columns</a>
+ it's not allowed to enable <em>batch mode</em> for insert operations.
+ <br/>
+ When using <a href="site:lock-manager/optimistic-locking">optimistic locking</a> the
+ version check will always succeed for update operations when <em>batch-mode</em>
+ is enabled - take care!!.
+ <br/>
+ <br/>
+ OJB 1.0.5 and later:
+ <br/>
+ The issue caused by <a href="site:sequence-manager/identity-columns">database identity columns</a>
+ on insert is fixed.
+ <br/>
+ The issue caused by classes using <a href="site:lock-manager/optimistic-locking">optimistic locking</a>
+ is fixed by temporarily disable batch-mode for update/delete of objects with optimistic locking.
+ A more sophisticated solution will be provided in next major release.
+ </note>
</section>
</section>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml Tue Oct 2 15:20:30 2007
@@ -71,28 +71,41 @@
<p>
To make OJB's
<em>ODMG-api</em> implementation proper work, some specific metadata settings
- needed in the
- <a href="site:repository">repository mapping files</a>.
+ needed in the <a href="site:repository">repository mapping files</a>.
</p>
<p>
- All defined
+ The behavior of the defined
<a href="site:repository/reference-descriptor">reference-descriptor</a> and
<a href="site:repository/collection-descriptor">collection-descriptor</a>
- need specific
- <em>auto-xxx</em> settings:
+ based on specific <em>auto-xxx</em> settings. The
+ <a href="site:basic-technique/manage-references"><em>auto-xxx</em> settings</a>
+ are primarily used by the <a href="site:pb-guide">PB-API</a> but the ODMG implementation
+ use/need some settings too.
+ <br/>
+ The following settings are supported when using the ODMG-API:
</p>
<ul>
<li>
auto-retrieve="true"
+ <br/>
+ mandatory setting (this is the default value used by OJB, no need
+ to specify this in the mapping files).
</li>
<li>
- auto_update="none"
+ auto-update="..."
+ <br/>
+ all settings are completely ignored (before OJB 1.0.5 auto-update="none" is mandatory)
</li>
<li>
- auto-delete="none", disable cascading delete, in this case the foreign key will
- be nullified, but the referenced object will not be deleted too) or use
+ auto-delete="object"
+ <br/>
+ (or 'true') enable cascading delete (since OJB 1.0.4)
<br/>
- auto-delete="object" (to enable cascading delete, since OJB 1.0.4!)
+ auto-delete="..."
+ <br/>
+ all values, except of 'object' and 'true', disable cascading
+ delete. In this case only the foreign key will be <em>nullified</em>, the referenced object
+ will not be deleted (only updated if necessary).
</li>
</ul>
<note>
@@ -105,40 +118,42 @@
</p>
<source><![CDATA[
<class-descriptor
- class="org.apache.ojb.odmg.shared.Master"
- table="MDTEST_MASTER"
+ class="org.Author"
+ table="AUTHOR"
>
<field-descriptor
- name="masterId"
- column="MASTERID"
+ name="id"
+ column="OJB_ID"
jdbc-type="INTEGER"
primarykey="true"
autoincrement="true"
/>
- <field-descriptor
- name="masterText"
- column="MASTER_TEXT"
- jdbc-type="VARCHAR"
- />
+...
<collection-descriptor
- name="collDetailFKinPK"
- element-class-ref="org.apache.ojb.odmg.shared.DetailFKinPK"
+ name="books"
+ element-class-ref="org.Book"
+ indirection-table="IC_PUBLICATION"
proxy="false"
auto-retrieve="true"
auto-update="none"
auto-delete="none"
>
- <inverse-foreignkey field-ref="masterId"/>
+ <fk-pointing-to-this-class column="AUTHOR_ID"/>
+ <fk-pointing-to-element-class column="BOOK_ID"/>
</collection-descriptor>
...
-</class-descriptor>]]></source>
+</class-descriptor>]]>
+...</source>
+ <p>
+ In the sample mapping classes <code>Author</code> has a m:n relation with class
+ <code>Book</code> (only the <code>Author</code> class mapping is showed). Cascading delete
+ is disabled.
+ </p>
<p>
A lot of mapping samples can be found in mappings for the
- <a href="site:test-suite">OJB test suite</a>. All mappings for the ODMG unit test
- are in
- <code>repository_junit_odmg.xml</code> file, which can be found under the
- <em>src/test</em>
- directory.
+ <a href="site:test-suite">OJB test suite</a>. All mappings for the ODMG unit
+ tests are in the <code>repository_junit_odmg.xml</code> file, which can be found
+ under the <em>src/test</em> directory.
</p>
</section>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml Tue Oct 2 15:20:30 2007
@@ -398,7 +398,8 @@
<li>
if you have an application that has a lot of object lookups by identity/primary
key, OJB can be much faster than a native JDBC application layer without caching extensions
- (the "real world test" show 50-80 times faster <em>lookup by primary key</em>)
+ (the "real world test" show 50-80 times faster <em>lookup by primary key</em> if the object
+ is found in cache)
</li>
<li>
if the JDBC-layer doesn't use batch statements, OJB can overall show a better
@@ -413,7 +414,7 @@
This simple test only compares the power of OJB and a JDBC-layer
relating to a simple "flat" POJO object. Dealing with complex object graphs
can give different results (dependent on the used metadata settings - e.g. use
- of proxy references, ...).
+ of lazy loading for references, ...).
</note>
</section>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml Tue Oct 2 15:20:30 2007
@@ -711,47 +711,38 @@
<anchor id="prefetched-relations"/>
<section>
- <title>prefetched relationships</title>
+ <title>Prefetching of relationships</title>
+ <p>
+ This feature can help to minimize the number of queries when reading objects with
+ relationships (if <a href="site:basic-technique/auto-retrieve">auto-retrieve is enabled</a> and
+ <a href="site:basic-technique/reference-proxy">lazy-loading</a> wasn't used).
+ <br/>
+ In case we query for class <code>ProductGroup</code> with a 1:n relationship to class
+ <code>Article</code>. One query is executed to get the <code>ProductGroup</code> objects
+ and for <strong>each</strong> <code>ProductGroup</code> object another query is executed
+ to retrieve the <code>Article</code> objects of the 1:n reference.
+ </p>
+ <p>
+ With prefetched relationships OJB tries to read all <code>Article</code> objects belonging
+ to the <code>ProductGroup</code> objects in <strong>one</strong> query using a SQL-IN clause:
+ </p>
<p>
- This feature can help to minimize the number of queries when reading objects with relationships.
- In our Testcases we have ProductGroups with a one to many relationship to Articles.
- When reading the ProductGroups one query is executed to get the ProductGroups and for
- <strong>each</strong> ProductGroup
- another query is executed to retrieve the Articles.
- </p>
- <p>
- With prefetched relationships OJB tries to read all Articles belonging to the ProductGroups in
- <strong>one</strong> query.
- See further down why one query is not always possible.
- </p>
- <source><![CDATA[
-Criteria crit = new Criteria();
-crit.addLessOrEqualThan("groupId", new Integer(5));
-
-QueryByCriteria q = QueryFactory.newQuery(ProductGroup.class, crit);
-q.addOrderByDescending("groupId");
-q.addPrefetchedRelationship("allArticlesInGroup");
-
-Collection results = broker.getCollectionByQuery(q);]]></source>
- <p>
The first query reads all matching ProductGroups:
- </p>
- <source><![CDATA[
+ </p>
+ <source><![CDATA[
SELECT ... FROM Kategorien A0 WHERE
A0.Kategorie_Nr <= ? ORDER BY 3 DESC]]></source>
<p>
- The second query retrieves Articles belonging to the ProductGroups read by the first query:
- </p>
- <source><![CDATA[
+ The second query retrieve all <code>Article</code> objects belonging to the
+ <code>ProductGroup</code> objects read by the first query:
+ </p>
+ <source><![CDATA[
SELECT ... FROM Artikel A0 WHERE A0.Kategorie_Nr
IN ( ? , ? , ? , ? , ? ) ORDER BY 7 DESC]]></source>
- <p>
- After reading all Articles they are associated with their ProductGroup.
- </p>
- <note>
- This function is not yet supported for relationships using Arrays.
- </note>
- <p>
+ <p>
+ After reading all <code>Article</code> they are associated with their <code>ProductGroup</code>.
+ </p>
+ <p>
Some databases limit the number of parameters in an IN-statement.
If the limit is reached OJB will split up the second query into multiple queries,
the limit is set to 3 for the following sample:
@@ -761,10 +752,35 @@
IN ( ? , ? , ? ) ORDER BY 7 DESC
SELECT ... FROM Artikel A0 WHERE A0.Kategorie_Nr
IN ( ? , ? ) ORDER BY 7 DESC]]></source>
- <p>
+ <p>
The IN-limit for prefetch can be defined in OJB.properties
<a href="#in-not-in">SqlInLimit</a>.
</p>
+
+ <p>
+ Since version 1.0.3 OJB automatically prefetch relationships whenever it's possible.
+ </p>
+ <p>
+ For backward compatibility OJB still provide methods for manual prefetching, but since version
+ 1.0.5 manual settings are disabled.
+ </p>
+ <anchor id="manual-prefetching"/>
+ <p>
+ <strong>manual prefetching (older versions of OJB)</strong>:
+ </p>
+ <source><![CDATA[
+Criteria crit = new Criteria();
+crit.addLessOrEqualThan("groupId", new Integer(5));
+
+QueryByCriteria q = QueryFactory.newQuery(ProductGroup.class, crit);
+q.addOrderByDescending("groupId");
+q.addPrefetchedRelationship("allArticlesInGroup");
+
+Collection results = broker.getCollectionByQuery(q);]]></source>
+ <note>
+ The prefetching function is not yet supported for relationships using Arrays.
+ </note>
+
</section>
<anchor id="query-by-identity"/>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml Tue Oct 2 15:20:30 2007
@@ -386,51 +386,14 @@
<p>
The
<em>batch-mode</em>
- attribute is the general property to enable the use of JDBC batch statement
- by OJB (if supported by the used database) - 'true' enables the per-session
- batch mode, whereas 'false' prohibits it in general.
- <br/>
- To switch on/off OJB's batch mode at runtime use method
- </p>
- <source><![CDATA[
-PersistenceBroker.serviceConnectionManager.setBatchMode(...)]]></source>
- <note>
- Not until this method activate OJB's batch mode, OJB will use batch statements.
- The <em>batch-mode</em> attribute in the <code>jdbc-connection-descriptor</code> only
- enable the use use of batch statements - e.g. so it's possible to completely disable the
- use of batch statements (<em>batch-mode</em> set 'false') independent from the
- <code>setBatchMode(...)</code> calls in the source code.
- <br/>
- <br/>
- On <code>PersistenceBroker.close()</code> call
- OJB always switches off batch mode, thus you have to call
- <code>ConnectionManager.setBatchMode(true)</code> on each
- new obtained PB instance again.
- </note>
- <p>
- This setting can dramatically improve performance for mass insert/update/delete
- operations of same object type.
+ attribute is the general property to activate the use of JDBC <em>batch statement</em>
+ by OJB (if supported by the used database) - 'true' makes possible to use the
+ per-session batch mode support, whereas 'false' prohibits it in general.
+ <br/>
+ If attribute <em>batch-mode</em> is set <em>true</em> it is possible to switch
+ <a href="site:connection/batch">on/off OJB's batch mode at runtime
+ (see connection handling guide)</a>.
</p>
- <note>
- OJB 1.0.4 and earlier:
- <br/>
- When using <a href="site:sequence-manager/identity-columns">database identity columns</a>
- it's not allowed to enable <em>batch mode</em> for insert operations.
- <br/>
- When using <a href="site:lock-manager/optimistic-locking">optimistic locking</a> the
- version check will always succeed for update operations when <em>batch-mode</em>
- is enabled - take care!!.
- <br/>
- <br/>
- OJB 1.0.5 and later:
- <br/>
- The issue caused by <a href="site:sequence-manager/identity-columns">database identity columns</a>
- on insert is fixed.
- <br/>
- The issue caused by classes using optimistic locking is fixed by temporarily disable
- batch-mode for all objects with optimistic locking. A more sophisticated solution will
- be provided in next major release.
- </note>
<p>
The
<em>useAutoCommit</em>
@@ -1609,8 +1572,9 @@
<p>
A reference-descriptor contains mapping info for an attribute of a
persistent class that is not primitive but references another
- persistent entity Object. More about
- <a href="site:basic-technique/one-to-one">1:1 references here</a>.
+ persistent entity object. It's used to map
+ <a href="site:basic-technique/one-to-one">1:1 references</a> or to
+ map a specific <a href="site:advanced-technique/table-per-subclass">kind of inheritance</a>.
</p>
<p>
A <em>foreignkey</em> element contains information on foreign key columns that
@@ -1644,7 +1608,7 @@
The <em>refresh</em> attribute can be set to <em>true</em> to force OJB to refresh
the object reference when the object is loaded from cache. If <em>true</em> OJB try to retrieve
the reference (dependent on the
- <a href="site:basic-technique/cascading">auto-xxx settings</a>) again when the main object
+ <a href="site:basic-technique/manage-references">auto-xxx settings</a>) again when the main object
is loaded from cache (normally only make sense for 1:n and m:n relations).
<br/>
This could be useful if the <a href="site:object-cache">ObjectCache implementation</a>
@@ -1669,7 +1633,7 @@
The <em>auto-update</em> attribute specifies whether OJB automatically stores
this reference attribute on storing the persistent object.
<br/>
- More info about the <a href="site:basic-technique/cascading">auto-XXX settings here</a>.
+ More info about the <a href="site:basic-technique/manage-references">auto-XXX settings here</a>.
</p>
<note>
This attribute must be set to <em>false</em> if using the OTM or JDO layer.
@@ -1680,7 +1644,7 @@
The <em>auto-delete</em> attribute specifies whether OJB automatically deletes
this reference attribute on deleting the persistent object.
<br/>
- More info about the <a href="site:basic-technique/cascading">auto-XXX settings here</a>.
+ More info about the <a href="site:basic-technique/manage-references">auto-XXX settings here</a>.
</p>
<note>
This attribute must be set to <em>false</em> if using the OTM or JDO layer.
@@ -1820,7 +1784,7 @@
The <em>refresh</em> attribute can be set to <em>true</em> to force OJB to refresh
the object reference when the object is loaded from cache. If <em>true</em> OJB try to retrieve
the reference (dependent on the
- <a href="site:basic-technique/cascading">auto-xxx settings</a>) again when the main object
+ <a href="site:basic-technique/manage-references">auto-xxx settings</a>) again when the main object
is loaded from cache (normally only make sense for 1:n and m:n relations).
<br/>
This could be useful if the <a href="site:object-cache">ObjectCache implementation</a>
@@ -1846,7 +1810,7 @@
The <em>auto-update</em> attribute specifies whether OJB automatically stores
this reference attribute on storing the persistent object.
<br/>
- More info about the <a href="site:basic-technique/cascading">auto-XXX settings here</a>.
+ More info about the <a href="site:basic-technique/manage-references">auto-XXX settings here</a>.
</p>
<note>
This attribute must be set to <em>false</em> if using the OTM or JDO layer.
@@ -1857,7 +1821,7 @@
The <em>auto-delete</em> attribute specifies whether OJB automatically deletes
this reference attribute on deleting the persistent object.
<br/>
- More info about the <a href="site:basic-technique/cascading">auto-XXX settings here</a>.
+ More info about the <a href="site:basic-technique/manage-references">auto-XXX settings here</a>.
</p>
<note>
This attribute must be set to <em>false</em> if using the OTM or JDO layer.
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml Tue Oct 2 15:20:30 2007
@@ -2659,6 +2659,665 @@
</section>
+
+ <anchor id="inheritance"/>
+ <section>
+ <title>Inheritance</title>
+ <p>
+ In this section we describe the mapping of <em>inheritance hierarchies</em> via
+ OJB's <a href="ext:xdoclet">xdoclet</a>-module.
+ </p>
+ <p>
+ To map a class hierarchy to database tables we can choose one of the following solutions:
+ </p>
+ <ol>
+ <li>
+ <p>
+ <a href="#table-per-class">Map each class of a hierarchy to a distinct table</a> and have all
+ attributes from the base class in the derived class.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="#table-per-hierarchy">Map class hierarchy onto one table</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="#table-per-subclass">Map subclass fields of a hierarchy to a distinct table</a>,
+ but do not map super class fields to derived classes. Use joins to materialize over
+ all tables to materialize objects.
+ </p>
+ </li>
+ </ol>
+ <p>
+ Please read section <a href="site:advanced-technique/inheritance">Mapping Inheritance Hierarchies</a> for more
+ detailed information.
+ </p>
+
+ <anchor id="table-per-class"/>
+ <section>
+ <title>Table per class</title>
+ <p>
+ Map each class of a hierarchy to a distinct table and have all
+ attributes from the base class in the derived class. Detailed describtion
+ see <a href="site:advanced-technique/table-per-class">advanced techniques guide</a>.
+ </p>
+ <p>
+ This is the default mapping strategy for class hierarchies and the OJB-xdoclet module
+ generates the correct mapping out of the box for all classes in the hierarchy if the
+ <a href="#ojb.class">@ojb.class</a> tag is specified.
+ </p>
+ <p>
+ The mandatory tag declaration (with xdoclet-module default settings) is:
+ </p>
+ <ul>
+ <li>
+ The <a href="#ojb.class">@ojb.class</a> tag for each class in the hierarchy.
+ </li>
+ </ul>
+ <p>
+ Usage example: Class C extends class B, class B extends class A
+ </p>
+ <source><![CDATA[
+/** @ojb.class */
+public class A
+{
+ /** @ojb.field primarykey="true"
+ * autoincrement="ojb"
+ */
+ private Integer attr;
+ /** @ojb.field length="128" */
+ private String name;
+}
+
+/** @ojb.class
+ */
+public class B extends A
+{
+ /** @ojb.field length="128" */
+ private String nameB;
+}
+
+/** @ojb.class
+ */
+public class C extends B
+{
+ /** @ojb.field length="128" */
+ private String nameC;
+}]]></source>
+ <p>
+ This generates the following OJB and database mapping:
+ </p>
+ <source><![CDATA[
+<class-descriptor
+ class="test.A"
+ table="A"
+>
+ <extent-class class-ref="test.B"/>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ access="readwrite"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="name"
+ column="name"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+</class-descriptor>
+<class-descriptor
+ class="test.B"
+ table="B"
+>
+ <extent-class class-ref="test.C"/>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ access="readwrite"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="name"
+ column="name"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="nameB"
+ column="nameB"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+</class-descriptor>
+<class-descriptor
+ class="test.C"
+ table="C"
+>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ access="readwrite"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="name"
+ column="name"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="nameB"
+ column="nameB"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="nameC"
+ column="nameC"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+</class-descriptor>]]></source>
+ <p>
+ Database mapping:
+ </p>
+ <source><![CDATA[
+<table name="A">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="name"
+ javaName="name"
+ type="VARCHAR"
+ size="128"
+ />
+</table>
+<table name="B">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="name"
+ javaName="name"
+ type="VARCHAR"
+ size="128"
+ />
+ <column name="nameB"
+ javaName="nameB"
+ type="VARCHAR"
+ size="128"
+ />
+</table>
+<table name="C">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="name"
+ javaName="name"
+ type="VARCHAR"
+ size="128"
+ />
+ <column name="nameB"
+ javaName="nameB"
+ type="VARCHAR"
+ size="128"
+ />
+ <column name="nameC"
+ javaName="nameC"
+ type="VARCHAR"
+ size="128"
+ />
+</table>]]></source>
+ <p>
+ All inherited fields are included in the mapping files of the sub-classes. If (abstract or
+ non-abstract) base classes with common fields for all classes of the project (e.g. fields like: id,
+ lastModified, version, ...) are used please read the <a href="#hint-base-class">hint below</a>.
+ </p>
+ </section>
+
+ <anchor id="table-per-hierarchy"/>
+ <section>
+ <title>Table per hierachy</title>
+ <p>
+ Map a class hierarchy onto one table. Detailed describtion
+ see <a href="site:advanced-technique/table-per-hierarchy">advanced techniques guide</a>.
+ </p>
+ <p>
+ The mandatory tag declaration (with xdoclet-module default settings) is:
+ </p>
+ <ul>
+ <li>
+ The <a href="#ojb.class">@ojb.class</a> tag for each class in the hierarchy
+ with identical attribute <em>table</em> values (table names) set.
+ </li>
+ <li>
+ The root class of the hierarchy defines a <em>VARCHAR</em> field called
+ <em>ojbConcreteClass</em>.
+ </li>
+ </ul>
+ <p>
+ Usage example: Class C extends class B, class B extends class A
+ </p>
+ <source><![CDATA[
+/** @ojb.class
+ * table="ABC"
+ */
+public class A
+{
+ /** @ojb.field primarykey="true"
+ * autoincrement="ojb"
+ */
+ private Integer attr;
+ /** @ojb.field */
+ private String ojbConcreteClass;
+ /** @ojb.field length="128" */
+ private String name;
+}
+
+/** @ojb.class
+ * table="ABC"
+ */
+public class B extends A
+{
+ /** @ojb.field length="128" */
+ private String nameB;
+}
+
+/** @ojb.class
+ * table="ABC"
+ */
+public class C extends B
+{
+ /** @ojb.field length="128" */
+ private String nameC;
+}]]></source>
+ <p>
+ The generated OJB specific mapping is very similar to the mapping in
+ <a href="#table-per-class">table per class</a>, except of the table name and
+ the extra field <em>ojbConcreteClass</em>:
+ </p>
+<source><![CDATA[
+<class-descriptor
+ class="test.A"
+ table="ABC"
+>
+ <extent-class class-ref="test.B"/>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="ojbConcreteClass"
+ column="ojbConcreteClass"
+ jdbc-type="VARCHAR"
+ length="254"
+ >
+ ...
+
+</class-descriptor>
+<class-descriptor
+ class="test.B"
+ table="ABC"
+>
+ <extent-class class-ref="test.C"/>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="ojbConcreteClass"
+ column="ojbConcreteClass"
+ jdbc-type="VARCHAR"
+ length="254"
+ >
+ ...
+
+</class-descriptor>
+<class-descriptor
+ class="test.C"
+ table="ABC"
+>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="ojbConcreteClass"
+ column="ojbConcreteClass"
+ jdbc-type="VARCHAR"
+ length="254"
+ >
+ ...
+
+ </field-descriptor>
+</class-descriptor>]]></source>
+ <p>
+ The generated database mapping look like:
+ </p>
+ <source><![CDATA[
+<table name="ABC">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="ojbConcreteClass"
+ javaName="ojbConcreteClass"
+ type="VARCHAR"
+ size="254"
+ />
+ <column name="name"
+ javaName="name"
+ type="VARCHAR"
+ size="128"
+ />
+ <column name="nameB"
+ javaName="nameB"
+ type="VARCHAR"
+ size="128"
+ />
+ <column name="nameC"
+ javaName="nameC"
+ type="VARCHAR"
+ size="128"
+ />
+</table>]]></source>
+ </section>
+
+ <anchor id="table-per-subclass"/>
+ <section>
+ <title>Table per sub-class</title>
+ <p>
+ Map sub-class fields of a class hierarchy to a distinct table for each sub-class,
+ but do not map super-class fields to derived class tables. Use joins to materialize over
+ all tables to materialize objects. Detailed describtion
+ see <a href="site:advanced-technique/table-per-subclass">advanced techniques guide</a>.
+ </p>
+ <p>
+ The mandatory tag declaration (with xdoclet-module default settings) is:
+ </p>
+ <ul>
+ <li>
+ The <a href="#ojb.class">@ojb.class</a> tag for each class in the hierarchy.
+ </li>
+ <li>
+ A <a href="#ojb.reference">@ojb.reference</a> tag for each sub-class in the hierarchy.
+ </li>
+ </ul>
+ <p>
+ Usage example: Class C extends class B, class B extends class A
+ </p>
+ <source><![CDATA[
+/** @ojb.class */
+public class A
+{
+ /** @ojb.field primarykey="true"
+ * autoincrement="ojb"
+ */
+ private Integer attr;
+ /** @ojb.field length="128" */
+ private String name;
+}
+
+/** @ojb.class
+ * @ojb.reference class-ref="super"
+ */
+public class B extends A
+{
+ /** @ojb.field length="128" */
+ private String nameB;
+}
+
+/** @ojb.class
+ * @ojb.reference class-ref="super"
+ */
+public class C extends B
+{
+ /** @ojb.field length="128" */
+ private String nameC;
+}]]></source>
+ <p>
+ The generated OJB specific mapping shows in all sub-classes only the additional fields
+ of the sub-class - except the primary key field(s) are inherited in each sub-class. Each
+ sub-class declares a specific <a href="site:repository/reference-descriptor">reference-descriptor</a>
+ pointing to the super-class:
+ </p>
+ <source><![CDATA[
+<class-descriptor
+ class="test.A"
+ table="A"
+>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="name"
+ column="name"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+</class-descriptor>
+<class-descriptor
+ class="test.B"
+ table="B"
+>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ access="readwrite"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="nameB"
+ column="nameB"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+ <reference-descriptor
+ name="super"
+ class-ref="test.A"
+ >
+ </reference-descriptor>
+</class-descriptor>
+<class-descriptor
+ class="test.C"
+ table="C"
+>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ access="readwrite"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="nameC"
+ column="nameC"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+ <reference-descriptor
+ name="super"
+ class-ref="test.B"
+ >
+ </reference-descriptor>
+</class-descriptor>]]></source>
+ <p>
+ The generated database mapping look like:
+ </p>
+ <source><![CDATA[
+<table name="A">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="name"
+ javaName="name"
+ type="VARCHAR"
+ size="128"
+ />
+</table>
+<table name="B">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="nameB"
+ javaName="nameB"
+ type="VARCHAR"
+ size="128"
+ />
+ <foreign-key foreignTable="A">
+ <reference local="attr" foreign="attr"/>
+ </foreign-key>
+</table>
+<table name="C">
+ <column name="attr"
+ javaName="attr"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"
+ />
+ <column name="nameC"
+ javaName="nameC"
+ type="VARCHAR"
+ size="128"
+ />
+ <foreign-key foreignTable="B">
+ <reference local="attr" foreign="attr"/>
+ </foreign-key>
+</table>
+ ]]></source>
+ <p>
+ By default the module automatically generates FK constraints. To disable this, please
+ refer to <a href="#ojb.reference">@ojb.reference database-foreignkey</a>.
+ </p>
+ </section>
+
+
+ <anchor id="hint-base-class"/>
+ <section>
+ <title>Hint: How to handle base classes (of persistence capable objects)</title>
+ <p>
+ In many cases persistence capable objects are inherited from a (abstract) base class with
+ all common fields defined (e.g. primary key field, version field, a last modified field, ...).
+ But this base class will never be requested in the application, thus a O/R-mapping isn't needed.
+ <br/>
+ Only declare <a href="#ojb.field">@ojb.field</a> tags on the fields to inherit, don't declare
+ the <a href="#ojb.class">@ojb.class</a> tag in the base class. In this case only the fields
+ will be inherited, no inheritence mapping will be generated.
+ </p>
+ <source><![CDATA[
+/** */
+public class Base
+{
+ /** @ojb.field primarykey="true"
+ * autoincrement="database"
+ * access="readonly"
+ */
+ private Integer attr;
+ /** @ojb.field */
+ private int version;
+}
+
+/** @ojb.class */
+public class A extends Base
+{
+ /** @ojb.field length="128" */
+ private String nameA;
+}]]></source>
+ <p>
+ The generated OJB mapping:
+ </p>
+ <source><![CDATA[
+<class-descriptor
+ class="test.A"
+ table="A"
+>
+ <field-descriptor
+ name="attr"
+ column="attr"
+ jdbc-type="INTEGER"
+ primarykey="true"
+ autoincrement="true"
+ access="readonly"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="version"
+ column="version"
+ jdbc-type="INTEGER"
+ >
+ </field-descriptor>
+ <field-descriptor
+ name="nameA"
+ column="nameA"
+ jdbc-type="VARCHAR"
+ length="128"
+ >
+ </field-descriptor>
+</class-descriptor>
+ ]]></source>
+ </section>
+ </section>
+
+
+
+
<section>
<title>Nested objects</title>
<p/>
@@ -2770,7 +3429,8 @@
* @ojb.nested
* @ojb.modify-nested name="hasValue"
* jdbc-type="INTEGER"
- * conversion="org.apache.ojb.broker.accesslayer.conversions.Boolean2IntFieldConversion"
+ * conversion=
+ * "org.apache.ojb.broker.accesslayer.conversions.Boolean2IntFieldConversion"
* id="3"
* @ojb.modify-nested name="id"
* primarykey=""
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/howtos/howto-use-lobs.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/howtos/howto-use-lobs.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/howtos/howto-use-lobs.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/howtos/howto-use-lobs.xml Tue Oct 2 15:20:30 2007
@@ -279,7 +279,7 @@
...
ByteArrayInputStream in2 = new ByteArrayInputStream(...);
StringReader reader2 = new StringReader(...);
-// update object using new LOB objets
+// update object using new LOB objects
broker.beginTransaction();
Blob b_update = broker.serviceLobHelper().newBlob(in2);
Clob c_update = broker.serviceLobHelper().newClob(reader2);
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml Tue Oct 2 15:20:30 2007
@@ -77,7 +77,7 @@
need specific metadata settings on relationship definition, the mandatory settings
are listed in the
<a href="site:odmg-guide/metadata">ODMG-Guide</a> - additional info see
- <a href="site:basic-technique/cascading">auto-xxx settings</a> and
+ <a href="site:basic-technique/manage-references">auto-xxx settings</a> and
<a href="site:repository">repository file settings</a>.
</p>
<p>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml?rev=581418&r1=581417&r2=581418&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml Tue Oct 2 15:20:30 2007
@@ -487,9 +487,18 @@
<source><![CDATA[
Identity oid = broker.serviceIdentity().buildIdentity(Product.class, new Integer(23));
Product product = (Product) broker.getObjectByIdentity(oid);]]></source>
+ <p>
+ or using the <em>Criteria-API</em> (this cause small overhead, internally the methods described
+ above are used):
+ </p>
+ <source><![CDATA[
+Identity oid = broker.serviceIdentity().buildIdentity(Product.class, new Integer(23));
+Query q = QueryFactory.newQueryByIdentity(oid);
+Product product = (Product) broker.getObjectByQuery(q);
+ ]]></source>
<note>
If the persistent object use compound primary keys you have to specifiy
- all keys to get a distinct result.
+ all keys to get the correct result.
</note>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org