db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject svn commit: r518439 - in /db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation: ./ content/xdocs/ content/xdocs/docu/guides/
Date Thu, 15 Mar 2007 01:53:56 GMT
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


Mime
View raw message