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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]