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/03/15 02:53:56 UTC
svn commit: r518439 - in
/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation: ./
content/xdocs/ content/xdocs/docu/guides/
Author: arminw
Date: Wed Mar 14 18:53:55 2007
New Revision: 518439
URL: http://svn.apache.org/viewvc?view=rev&rev=518439
Log:
update, extend documentation
Modified:
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/lockmanager.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/metadata.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/sequencemanager.xml
db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/release-notes.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/skinconf.xml
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/lockmanager.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/lockmanager.xml?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/lockmanager.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/lockmanager.xml Wed Mar 14 18:53:55 2007
@@ -1400,9 +1400,9 @@
<p>
This implementation use the locking part of apache's
<a href="ext:commons-transaction">commons-transaction</a> api.
- The timeout of locks is currently (OJB 1.0.2) not supported, maybe
- in further versions. This implementation supports <em>blocking</em>
- (with deadlock detection) and <em>non-blocking</em> of acquired locks.
+ This implementation supports <em>blocking</em>
+ (with deadlock detection) and <em>non-blocking</em> of acquired write-locks
+ (to optimize performance on read-lock calls always non-blocking mode is used).
</p>
</section>
@@ -1481,6 +1481,20 @@
<!-- close pessimistic locking section -->
</section>
+
+
+ <anchor id="selectForUpdate"/>
+ <section>
+ <title>Pessimistic database based lock with "SELECT ... FOR UPDATE" clause</title>
+ <p>
+ It's possible to use pessimistic database based locking via <em>SELECT ... FOR UPDATE</em>
+ with OJB too. But this is currently not integrated in OJB's pessimistic in-memory Locking-API
+ (see <a href="ext:api/lock-manager">LockManager</a>).
+ <br/>
+ Please refer to the <a href="site:query/selectForUpdate">Query-guide</a> for more details.
+ </p>
+ </section>
+
<anchor id="odmg-locking"/>
<section>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/metadata.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/metadata.xml?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/metadata.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/metadata.xml Wed Mar 14 18:53:55 2007
@@ -444,8 +444,8 @@
<section>
<title>Reference runtime changes on per query basis</title>
<fixme author="arminw">
- Changes of reference settings on a per query basis will be supported with
- next upcoming release 1.1
+ Changes of reference settings on a per query basis will be supported
+ in next upcoming major release.
</fixme>
</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?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- 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 Wed Mar 14 18:53:55 2007
@@ -258,9 +258,125 @@
<section>
<title>Pagination and Limiting of query results</title>
<p>
- !!TODO!!
+ First, OJB supports two different mode to realize <em>pagination</em> and <em>limiting</em>
+ of query results:
+ </p>
+ <ul>
+ <li>
+ use of native database LIMIT and OFFSET clauses in the sql-queries based on the
+ limit-boundaries specified by the user to limit the result sets returned by the database
+ (depends on the database platform, some databases/jdbc-driver don't support limit/offset)
+ </li>
+ <li>
+ use of specific limit emulation classes which restrict the result set access using the
+ limit-boundaries specified by the user (no LIMIT/OFFSET extensions are used to build the
+ sql-query, OJB operates on the full result set)
+ </li>
+ </ul>
+ <p>
+ The first mode is recommended because it shows the best performance on large data amount.
+ If the database doesn't support native database based limit/offset OJB fallback to the
+ second mode. But it's also possible to explicit disable the native limit/offset using a
+ specific attribute in the mapping file - more details can be found in the
+ <a href="site:repository/jdbc-connection-descriptor-custom-attributes">repository guide
+ (attributes of the <em>jdbc-connection-descriptor</em>)</a>.
+ </p>
+ <p>
+ The <em>pagination</em> and <em>limiting</em> examples use class <code>Book</code> with
+ an 1:n reference to class <code>Review</code>.
+ </p>
+ <p>
+ Set the limit and paging boundaries in class <code>org.apache.ojb.broker.query.Query</code>
+ using methods:
+ </p>
+ <source><![CDATA[
+Query.setStartAtIndex(int startAtIndex);
+Query.setEndAtIndex(int endAtIndex);]]></source>
+ <p>
+ The index starts with number 1. To limit a query to return the first three objects
+ set <code>Query.setEndAtIndex(3)</code>.
+ </p>
+ <p>
+ Suppose we want to query the first 20 <code>Review</code>'s of a <code>Book</code> called
+ "A Confederacy of Dunces":
+ </p>
+ <source><![CDATA[
+Criteria crit = new Criteria()
+ .addEquals("book.title", "A Confederacy of Dunces");
+QueryByCriteria query = QueryFactory.newQuery(Review.class, crit);
+query.setWithExtents(false);
+query.setEndAtIndex(20);
+Collection result = broker.getCollectionByQuery(query);]]></source>
+ <p>
+ First build the <code>Criteria</code> object to find the <code>Book</code> title and
+ create a <code>Query</code>.
+ <br/>
+ If limit or paging is used it's recommended to query against
+ a real class (not an interface or abstract class) and to exclude
+ <a href="site:advanced-technique/extents">"extents"</a> (mapped sub-classes in different
+ tables) if OJB can't use "joins" to build a single query - this can be done with
+ <code>query.setWithExtents(false)</code>.
+ </p>
+ <note>
+ Otherwise OJB will perform multiple
+ limit queries (one for each mapped sub-class) and the query result can contain
+ <em>limit_or_pagination_size * subclass_count</em> number of objects (the summary of the
+ multiple queries).
+ </note>
+ <p>
+ If the target class
+ </p>
+ <ul>
+ <li>
+ is an interface or abstract class with exact one
+ <a href="site:advanced-technique/extents">"extent" class (real sub-/implementation-class)</a>
+ </li>
+ <li>
+ use a <a href="site:advanced-technique/table-per-hierarchy">single table for a class hierarchy</a>
+ mapping
+ </li>
+ <li>
+ use a <a href="site:advanced-technique/table-per-subclass">separate tables for each subclass</a>
+ mapping
+ </li>
+ </ul>
+ <p>
+ OJB will (normally) perform a single query and the paging/limit query result should contain
+ the expected number of objects.
+ </p>
+ <p>
+ Now suppose we want to query the same <code>Review</code> objects but now starting
+ with <code>Review</code> 21 up to 40, ordered by the user "vote":
+ </p>
+ <source><![CDATA[
+Criteria crit = new Criteria()
+ .addEquals("book.title", "A Confederacy of Dunces");
+QueryByCriteria query = QueryFactory.newQuery(Review.class, crit);
+query.addOrderByAscending("vote");
+query.addOrderByAscending("id");
+query.setWithExtents(false);
+query.setStartAtIndex(21);
+query.setEndAtIndex(40);
+
+Collection result = broker.getCollectionByQuery(query);]]></source>
+ <p>
+ The result will contain the 21th <code>Review</code> up to the 40th ordered by the
+ user vote.
+ </p>
+ <note>
+ If pagination is used it's strongly recommended to order by a unique column
+ to avoid problems with different result order when calling the next results (e.g. from 41 to 60)
+ because without ordering on a unique column the result is not determinably and the next
+ result can contain objects from the previous query.
+ <br/>
+ In the example above field <em>vote</em> isn't a unique column in the database (different user can
+ use the same vote value in their review), thus an additional order by expression based on a unique
+ database column was added (field <em>id</em> the mapped primary key column).
+ </note>
+ <p>
+ Special case: get only the fourth <code>Review</code> object. In this case
+ set <code>query.setStartAtIndex(4)</code> and <code>query.setEndAtIndex(4)</code>.
</p>
-
</section>
@@ -802,12 +918,38 @@
</section>
</section>
+
+ <anchor id="selectUpdate"/>
+ <section>
+ <title>Lock with "SELECT ... FOR UPDATE" clause</title>
+ <p>
+ TODO
+ </p>
+ <p>
+ Details about OJB's support for <em>optimistic locking</em> and the
+ <em>pessimistic in-memory locking API</em> can be found in the
+ <a href="site:lock-manager">Locking-guide</a>.
+ </p>
+ </section>
+
+ <anchor id="appendSql"/>
+ <section>
+ <title>Append user-defined SQL</title>
+ <p>
+ TODO
+ </p>
+ </section>
+
</section>
+
+
<anchor id="odmg-oql"/>
<section>
<title>ODMG OQL</title>
</section>
+
+
<anchor id="jdo-oql"/>
<section>
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?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- 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 Wed Mar 14 18:53:55 2007
@@ -84,6 +84,11 @@
xml-file.
</li>
</ol>
+ <p>
+ This guide describes all mapping elements supported by OJB. More details and examples about
+ how to use these elements can be found in other guides like
+ <a href="site:basic-technique">basic mapping</a> and <a href="site:advanced-technique">advanced mapping</a>
+ </p>
</section>
@@ -519,6 +524,14 @@
via <a href="#custom-attribute"><em>custom-attributes</em></a>.
</p>
<p>
+ Attribute <em>nativeLimitOffset</em>: If set <em>true</em> OJB use the native database
+ LIMIT and OFFSET syntax for
+ <a href="site:query/pagination">limit and paging queries</a> (if it's supported by the
+ DB and OJB's <a href="site:platform/declaration">Platform implementation class</a>).
+ If set 'false' OJB simulate limit and paging
+ by a specific result set iterator (this can result in bad performance on big result sets).
+ </p>
+ <p>
Attribute <em>initializationCheck</em> is an attribute to support backward
compatibility with OJB versions before 1.0.4.
<br/>
@@ -535,14 +548,6 @@
'autoCommit' state at connection initialization.
</p>
<p>
- Attribute <em>nativeLimitOffset</em>: If set <em>true</em> OJB use the native database
- LIMIT and OFFSET syntax for
- <a href="site:query/pagination">limit and paging queries</a> (if it's supported by the
- DB and OJB's <a href="site:platform/declaration">Platform implementation class</a>).
- If set 'false' OJB simulate limit and paging
- by a specific result set iterator (this can result in bad performance on big result sets).
- </p>
- <p>
Other platform specific settings are shown below.
</p>
<p>
@@ -554,6 +559,14 @@
>
<!--
+ If set 'true' OJB use the native database LIMIT and OFFSET syntax
+ for limit and paging queries (if it's supported by the database and OJB's Platform
+ implementation class). If set 'false' OJB simulate limit and paging by a specific
+ result set iterator (this can result in bad performance on big result sets).
+ -->
+ <attribute attribute-name="nativeLimitOffset" attribute-value="true" />
+
+ <!--
On initialization of connections the ConnectionFactory change the 'autoCommit'
state dependent of the used 'useAutoCommit' setting. This doesn't work in all
situations/environments, thus for useAutoCommit="1" the ConnectionFactory does
@@ -566,27 +579,21 @@
-->
<attribute attribute-name="initializationCheck" attribute-value="false" />
- <!--
- If set 'true' OJB use the native database LIMIT and OFFSET syntax
- for limit and paging queries (if it's supported by the DB and OJB's Platform
- implementation class). If set 'false' OJB simulate limit and paging by a specific
- result set iterator (this can result in bad performance on big result sets).
- -->
- <attribute attribute-name="nativeLimitOffset" attribute-value="true" />
-
<!-- ** Attributes with name prefix "platform." are used to allow database
platform class specific settings (PlatformXYZImpl classes) -->
- <!-- If set to value >0 Oracle's implicit statement caching will be enabled by OJB (Oracle9i
- or higher). Number of cached statements per connection using implicit caching with Oracle9i
- Connections. See http://
- otn.oracle.com/sample_code/tech/java/sqlj_jdbc/files/jdbc30/StmtCacheSample/Readme.html-->
+ <!-- If set to value >0 Oracle's implicit statement caching will be
+ enabled by OJB (Oracle9i or higher).
+ Number of cached statements per connection using implicit caching with Oracle9i Connections.
+ See http://otn.oracle.com/sample_code/tech/java/sqlj_jdbc/files/
+ jdbc30/StmtCacheSample/Readme.html-->
<attribute attribute-name="platform.oracle.statementCacheSize" attribute-value="15" />
<!-- Number of rows pre-fetched by the JDBC-driver for each executed query, when using row
pre-fetching with Oracle Connections (Oracle9i or higher). Note: this setting can be overridden
- by specifying a connection-pool attribute with name="jdbc.defaultRowPrefetch". See http://
- otn.oracle.com/sample_code/tech/java/sqlj_jdbc/files/advanced/RowPrefetchSample/Readme.html -->
+ by specifying a connection-pool attribute with name="jdbc.defaultRowPrefetch".
+ See http://otn.oracle.com/sample_code/tech/java/sqlj_jdbc/files/
+ advanced/RowPrefetchSample/Readme.html -->
<attribute attribute-name="platform.oracle.prefetchSize" attribute-value="20" />
<!-- If set to value >0 Oracle's native batch statement handling will be enabled by OJB
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml Wed Mar 14 18:53:55 2007
@@ -744,13 +744,19 @@
<attribute attribute-name="seq.generatedKeys" attribute-value="true"/>
</sequence-manager>]]></source>
<p>
- With the custom attribute <em>seq.generatedKeys</em> it's possible to decide how
+ With the custom attribute <em>seq.generatedKeys</em> (since OJB 1.0.5) it's possible to decide how
OJB lookup the generated database identity key. If set <em>true</em> OJB use the JDBC 3.0 method
<code>Statement.getGeneratedKeys()</code> to obtain generated database identity keys. If set
<em>false</em> OJB use a separate database specific <em>"last identity call"</em> query to
request the generated identity key. By default the JDBC 3.0 method call is used, if supported by
the database driver.
</p>
+ <note>
+ If <em>seq.generatedKeys</em> is enabled OJB expects that JDBC 3.0 property <em>generatedKeys</em>
+ is enabled by default in the JDBC-driver (OJB currently doesn't use
+ <code>Statement.RETURN_GENERATED_KEYS</code> to enable <em>generatedKeys</em> feature at runtime).
+ So take care that your database/driver supports this by default.
+ </note>
<p>
To declare the identity column in the persistent class mapping
<a href="site:repository/class-descriptor">class-descriptor</a>, add the
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/release-notes.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/release-notes.xml?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/release-notes.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/release-notes.xml Wed Mar 14 18:53:55 2007
@@ -17,7 +17,7 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">
<document>
<header>
- <title>OJB Release Notes</title>
+ <title>Release Notes</title>
</header>
<body>
<source><![CDATA[@@content@@]]></source>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml Wed Mar 14 18:53:55 2007
@@ -107,9 +107,6 @@
<guides label="Reference Guides" href="guides/" tab="ref-guides">
<summary label="Summary" href="summary.html"/>
- <!-- auto-generated html-site of repository.dtd -->
- <repository-html href="dtdx/repository.dtdx.html"/>
-
<pb-guide label="PB API guide" href="pb-guide.html">
<lookup-pb href="#lookup-pb"/>
<multiple-databases href="#multiple-databases"/>
@@ -140,6 +137,7 @@
<introduction href="#introduction"/>
<descriptor-repository href="#descriptor-repository"/>
<jdbc-connection-descriptor href="#jdbc-connection-descriptor"/>
+ <jdbc-connection-descriptor-custom-attributes href="#jdbc-connection-descriptor-custom-attributes"/>
<jcd-attributes href="#jcd-attributes"/>
<connection-pool href="#connection-pool"/>
<class-descriptor href="#class-descriptor"/>
@@ -158,6 +156,10 @@
<stored-procedures href="#stored-procedures"/>
<batch-mode href="#batch-mode"/>
</repository>
+
+ <!-- auto-generated html-site of repository.dtd -->
+ <repository-html href="dtdx/repository.dtdx.html"/>
+
<basic-technique label="Basic mapping" href="basic-technique.html">
<one-to-one href="#one-to-one"/>
<one-to-n href="#one-to-n"/>
@@ -200,6 +202,7 @@
<ordering href="#ordering"/>
<pagination href="#pagination"/>
<subqueries href="#subqueries"/>
+ <selectForUpdate href="#selectForUpdate"/>
</query>
<metadata label="Metadata handling" href="metadata.html">
<when-read-in href="#when-read-in"/>
Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/skinconf.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/skinconf.xml?view=diff&rev=518439&r1=518438&r2=518439
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/skinconf.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/skinconf.xml Wed Mar 14 18:53:55 2007
@@ -182,6 +182,10 @@
in the class attribute of a <p> node.
e.g. <p class="quote"/>
-->
+ #apphead h2 em {
+ color: #000000;
+ }
+
p.quote {
margin-left: 2em;
padding: .5em;
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org