arminw 2005/03/24 09:54:18
Modified: src/doc/forrest/src/documentation/content/xdocs/docu/guides
Tag: OJB_1_0_RELEASE connection.xml query.xml
repository.xml summary.xml
src/doc/forrest/src/documentation/content/xdocs/docu/tutorials
Tag: OJB_1_0_RELEASE odmg-tutorial.xml
pb-tutorial.xml
src/doc/forrest/src/documentation/content/xdocs/docu Tag:
OJB_1_0_RELEASE faq.xml
src/doc/forrest/src/documentation/content/xdocs Tag:
OJB_1_0_RELEASE site.xml
Added: src/doc/forrest/src/documentation/content/xdocs/docu/guides
Tag: OJB_1_0_RELEASE odmg-guide.xml pb-guide.xml
Log:
update tutorials
add new PB- and ODMG-Guide
Revision Changes Path
No revision
No revision
1.1.2.2 +25 -1
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml
Index: connection.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/connection.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- connection.xml 27 Jul 2004 00:29:31 -0000 1.1.2.1
+++ connection.xml 24 Mar 2005 17:54:17 -0000 1.1.2.2
@@ -263,6 +263,30 @@
</p>
</section>
+ <anchor id="open-close-connection"/>
+ <section>
+ <title>When does OJB open/close a connection</title>
+ <p>
+ This is dependent on the used OJB api. Generally OJB try
to obtain a connection as late as
+ possible and close the connection as soon as possible.
+ </p>
+ <p>
+ Using the <link href="site:pb-guide">PB-api</link> the
connection is obtained when
+ <link
href="ext:persistence-broker"><code>PersistenceBroker.beginTransaction()</code></link>
+ was called or a query is executed.
+ <br/>
+ On <code>PersistenceBroker.commitTransaction()</code> or
+ <code>PersistenceBroker.abortTransaction()</code> call
the connection was released. If no PB-tx is
+ running, the connection will be released on
<code>PersistenceBroker.close()</code> call.
+ </p>
+ <p>
+ Using the <link href="site:odmg-guide">ODMG-api</link>
the connection is obtained when a query is
+ executed or when the transaction commit. On leaving the
commit method, the connection will be released.
+ <br/>
+ All other top-level API should behave similar.
+ </p>
+ </section>
+
</section>
</body>
</document>
\ No newline at end of file
1.1.2.2 +3 -2
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml
Index: query.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/query.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- query.xml 8 Sep 2004 18:37:57 -0000 1.1.2.1
+++ query.xml 24 Mar 2005 17:54:17 -0000 1.1.2.2
@@ -757,11 +757,12 @@
</section>
</section>
+ <anchor id="odmg-oql"/>
<section>
<title>ODMG OQL</title>
</section>
-
+ <anchor id="jdo-oql"/>
<section>
<title>JDO queries</title>
</section>
1.1.2.5 +5 -3
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
Index: repository.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- repository.xml 18 Mar 2005 22:29:26 -0000 1.1.2.4
+++ repository.xml 24 Mar 2005 17:54:17 -0000 1.1.2.5
@@ -92,9 +92,10 @@
<p>
The
<em>descriptor-repository</em> is the root element of a
repository.xml file.
- It consists of one
+ It consists of one or more
<em>jdbc-connection-descriptor</em> and at least one
- <em>class-descriptor</em> element.
+ <em>class-descriptor</em> element. But it's also
possible to startup OJB without
+ any of these elements and <link
href="site:metadata/without-repository">add them at runtime</link>.
</p>
<section>
@@ -1017,6 +1018,7 @@
</section>
+ <anchor id="reference-descriptor"/>
<section>
<title>reference-descriptor</title>
<p>
1.2.2.2 +11 -1
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/summary.xml
Index: summary.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/summary.xml,v
retrieving revision 1.2.2.1
retrieving revision 1.2.2.2
diff -u -r1.2.2.1 -r1.2.2.2
--- summary.xml 23 Jan 2005 03:09:13 -0000 1.2.2.1
+++ summary.xml 24 Mar 2005 17:54:17 -0000 1.2.2.2
@@ -35,6 +35,16 @@
<ul>
<li>
+ <link href="site:pb-guide">PB guide</link>
+ <br/>
+ This document explains specific usage of the
<em>PB-api</em>.
+ </li>
+ <li>
+ <link href="site:odmg-guide">ODMG guide</link>
+ <br/>
+ This document explains specific usage of the
<em>ODMG-api</em>.
+ </li>
+ <li>
<link href="site:query">OJB Queries</link>
<br/>
This document explains the usage of the query syntax.
No revision
Index: summary.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/summary.xml,v
retrieving revision 1.2.2.1
retrieving revision 1.2.2.2
diff -u -r1.2.2.1 -r1.2.2.2
--- summary.xml 23 Jan 2005 03:09:13 -0000 1.2.2.1
+++ summary.xml 24 Mar 2005 17:54:17 -0000 1.2.2.2
@@ -35,6 +35,16 @@
<ul>
<li>
+ <link href="site:pb-guide">PB guide</link>
+ <br/>
+ This document explains specific usage of the
<em>PB-api</em>.
+ </li>
+ <li>
+ <link href="site:odmg-guide">ODMG guide</link>
+ <br/>
+ This document explains specific usage of the
<em>ODMG-api</em>.
+ </li>
+ <li>
<link href="site:query">OJB Queries</link>
<br/>
This document explains the usage of the query syntax.
No revision
Index: summary.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/summary.xml,v
retrieving revision 1.2.2.1
retrieving revision 1.2.2.2
diff -u -r1.2.2.1 -r1.2.2.2
--- summary.xml 23 Jan 2005 03:09:13 -0000 1.2.2.1
+++ summary.xml 24 Mar 2005 17:54:17 -0000 1.2.2.2
@@ -35,6 +35,16 @@
<ul>
<li>
+ <link href="site:pb-guide">PB guide</link>
+ <br/>
+ This document explains specific usage of the
<em>PB-api</em>.
+ </li>
+ <li>
+ <link href="site:odmg-guide">ODMG guide</link>
+ <br/>
+ This document explains specific usage of the
<em>ODMG-api</em>.
+ </li>
+ <li>
<link href="site:query">OJB Queries</link>
<br/>
This document explains the usage of the query syntax.
1.1.2.1 +569 -0
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/Attic/odmg-guide.xml
1.1.2.1 +151 -0
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/Attic/pb-guide.xml
No revision
No revision
1.1.2.4 +13 -69
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml
Index: odmg-tutorial.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml,v
retrieving revision 1.1.2.3
retrieving revision 1.1.2.4
diff -u -r1.1.2.3 -r1.1.2.4
--- odmg-tutorial.xml 18 Mar 2005 22:29:27 -0000 1.1.2.3
+++ odmg-tutorial.xml 24 Mar 2005 17:54:17 -0000 1.1.2.4
@@ -29,11 +29,15 @@
<section>
<title>Introduction</title>
<p>
- The ODMG API is an implementation of the
- <link href="ext:odmg-group">ODMG 3.0</link>
- Object Persistence API. The ODMG API provides a higher-level
API and query
+ The <em>ODMG API</em> is an implementation of the
+ <link href="ext:odmg-group">ODMG 3.0 Object Persistence
API</link>.
+ The ODMG API provides a higher-level API and query
language based interface over the
- <link href="site:pb-tutorial">PersistenceBroker API</link>.
+ <link href="site:pb-guide">PersistenceBroker API</link>.
+ </p>
+ <p>
+ More detailed information can be found in the <link
href="site:odmg-guide">ODMG-guide</link>
+ and in the other <link href="site:guides/summary">reference
guides</link>.
</p>
<p>
This tutorial operates on a simple example class:
@@ -75,6 +79,10 @@
the same place and is described in the
<link href="site:getting-started">Getting started</link>
section.
</p>
+ <p>
+ Further information about the OJB odmg-api implementation
can be found in
+ the <link href="site:odmg-guide">ODMG guide</link>.
+ </p>
</section>
@@ -235,69 +243,5 @@
</p>
</section>
-
- <section>
- <title>Notes on Using the ODMG API</title>
- <section>
- <title>Transactions</title>
- <p>
- The ODMG API uses object-level transactions, compared to
the PersistenceBroker
- database-level transactions. An ODMG
- <code>Transaction</code> instance contains
- all of the changes made to the object model within the
context of that
- transaction, and will not commit them to the database
until the ODMG
- <code>Transaction</code> is committed. At that point it
will use a database
- transaction to ensure atomicity of its changes.
- </p>
- </section>
-
- <section>
- <title>Locks</title>
- <p>
- The ODMG specification includes several levels of locks
and isolation. These are
- explained in much more detail in the
- <link href="site:lock-manager">Locking</link>
- documentation.
- </p>
- <p>
- In the ODMG API, locks obtained on objects are locked
within the context
- of a transaction. Any object modified within the context
of a transaction will
- be stored with the transaction,
- other changes made to the same object instance by other
threads, ignoring the lock state
- of the object, will also be stored - so take care of
locking conventions.
- The ODMG locking conventions (obtain a write lock before
do any modifications on an object)
- ensure that an object can only be modified within the
transaction.
- </p>
- </section>
-
- <section>
- <title>Persisting Non-Transactional Objects</title>
- <p>
- Frequently, objects will be modified outside of the
context of an
- ODMG transaction, such as a data access object in a web
application.
- In those cases a persistent object can still be
modified, but not
- directly through the OMG ODMG specification. OJB
provides an extension
- to the ODMG specification for instances such as this.
Examine this code:
- </p>
- <source><![CDATA[
-public static void persistChanges(Product product)
-{
- Implementation impl = OJB.getInstance();
- TransactionExt tx = (TransactionExt) impl.newTransaction();
-
- tx.begin();
- tx.markDirty(product);
- tx.commit();
-}]]></source>
- <p>
- In this function the product is modified outside the
context of the
- transaction, and is then the changes are persisted
within a transaction.
- The
- <code>TransactionExt.markDirty()</code> method indicates
to the Transaction
- that the passed object has been modified, even if the
Transaction itself sees
- no changes to the object.
- </p>
- </section>
- </section>
</body>
</document>
1.1.2.3 +12 -32
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
Index: pb-tutorial.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -u -r1.1.2.2 -r1.1.2.3
--- pb-tutorial.xml 3 Oct 2004 15:27:54 -0000 1.1.2.2
+++ pb-tutorial.xml 24 Mar 2005 17:54:17 -0000 1.1.2.3
@@ -31,7 +31,7 @@
<section>
<title>Introduction</title>
<p>
- The PersistenceBroker API provides the lowest level
access to OJB's persistence engine.
+ The <em>PersistenceBroker API</em> provides the lowest
level access to OJB's persistence engine.
While it is a low-level API compared to the OTM, ODMG,
or JDO API's it is still very
straightforward to use.
</p>
@@ -41,6 +41,10 @@
point of access for all persistence operations in this
API.
</p>
<p>
+ More detailed information can be found in the <link
href="site:pb-guide">PB-guide</link>
+ and in the other <link
href="site:guides/summary">reference guides</link>.
+ </p>
+ <p>
This tutorial operates on a simple example class:
</p>
<source><![CDATA[
@@ -73,6 +77,10 @@
can be downloaded from the same place. It is described
in the
<link href="site:getting-started">Getting started</link>
section.
</p>
+ <p>
+ Further information about the OJB PB-api implementation can
be found in
+ the <link href="site:pb-guide">PB guide</link>.
+ </p>
</section>
@@ -448,36 +456,8 @@
</section>
-
+ <anchor id="exception-handling"/>
<section>
- <title>Notes on Using the PersistenceBroker API</title>
- <section>
- <title>Pooling PersistenceBrokers</title>
- <p>
- The
- <code>PersistenceBrokerFactory</code> pools
- <code>PersistenceBroker</code>
- instances. Using the
- <code>PersistenceBroker.close()</code> method releases
- the broker back to the pool under the default
implementation. For this reason
- the examples in this tutorial all retrieve, use, and
close a new broker
- for each logical transaction.
- </p>
- </section>
-
- <section>
- <title>Transactions</title>
- <p>
- Transactions in the PeristenceBroker API are database
level transactions.
- This differs from object level transactions. The broker
does not maintain
- a collection of modified, created, or deleted objects
until a commit is called --
- it operates on the database using the databases
transaction mechanism. If object
- level transactions are required, one ofthe higher level
API's (ODMG, JDO, or OTM)
- should be used.
- </p>
- </section>
-
- <section>
<title>Exception Handling</title>
<p>
Most
@@ -552,6 +532,6 @@
retrieve the broker, a not-null test is first performed
before closing the broker.
</p>
</section>
- </section>
+
</body>
</document>
No revision
No revision
1.1.2.6 +15 -73
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml
Index: faq.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml,v
retrieving revision 1.1.2.5
retrieving revision 1.1.2.6
diff -u -r1.1.2.5 -r1.1.2.6
--- faq.xml 23 Jan 2005 03:09:13 -0000 1.1.2.5
+++ faq.xml 24 Mar 2005 17:54:17 -0000 1.1.2.6
@@ -556,38 +556,8 @@
</question>
<answer>
<p>
- Yes you can! The ODMG implementation relies on PB
Queries internally!
- Several users (including myself) are doing this.
+ Please refer to the <link
href="site:odmg-guide/no-oql">ODMG-guide</link>.
</p>
- <p>
- If you have a look at the simple example below
- you will see how OJB Query objects can be used withing
ODMG transactions.
- <br/>
- The most important thing is to lock all objects returned
by a
- query to the current transaction before starting
manipulating
- these objects.
- <br/>
- Further on do not commit or close the obtained
PB-instance, this will be done
- by the ODMG transaction on
- <code>tx.commit() / tx.rollback()</code>.
- </p>
- <source>
-Transaction tx = odmg.newTransaction();
-tx.begin();
-....
-// cast to get intern used PB instance
-PersistenceBroker broker = ((HasBroker) tx).getBroker();
-...
-// build query
-QueryByCriteria query = ...
-// perform PB-query
-Collection result = broker.getCollectionByQuery(query);
-// use result
-...
-
-tx.commit();
-...
- </source>
</answer>
</faq>
@@ -1028,36 +998,7 @@
</question>
<answer>
<p>
- The
<code>org.apache.ojb.broker.PersistenceBrokerFactory</code> make several
- methods available:
- </p>
- <source><![CDATA[
-public PersistenceBroker createPersistenceBroker(PBKey key) throws
PBFactoryException;
-
-public PersistenceBroker createPersistenceBroker(String jcdAlias, String
user, String password)
- throws PBFactoryException;
-
-public PersistenceBroker defaultPersistenceBroker() throws
PBFactoryException;
- ]]></source>
- <p>
- Method <code>defaultPersistenceBroker()</code> can be
used if the attribute
- <link
href="site:repository/jdbc-connection-descriptor"><em>default-connection</em></link>
- is set <em>true</em> in
<em>jdbc-connection-descriptor</em>. It's a convenience method,
- useful when only one database is used.
- </p>
- <p>
- The standard way to lookup a broker instance is via
<code>org.apache.ojb.broker.PBKey</code>
- by specify <em>jcdAlias</em> (specified in the
- <link href="ext:repository_database.xml">repository file
(or sub file)</link>),
- <em>user</em> and <em>passwd</em>. If the user and
password is
- already set in <em>jdbc-connection-descriptor</em> it is
possible to lookup the broker
- instance only be specify the <em>jcdAlias</em> in PBKey:
- </p>
- <source><![CDATA[
-PBKey pbKey = new PBKey("myJcdAliasName");
-PersistenceBroker broker =
PersitenceBrokerFactory.createPersistenceBroker(pbKey);]]></source>
- <p>
- See <link href="#userPasswordNeeded">here too</link>.
+ Please refer to <link
href="site:pb-guide/lookup-pb">PB-guide</link>.
</p>
</answer>
</faq>
@@ -1069,17 +1010,7 @@
</question>
<answer>
<p>
- Obtain a <code>org.odmg.Implementation</code> instance
first, then create new
- <code>org.odmg.Database</code> instance and open this
instance by setting the used
- <link
href="site:repository/jdbc-connection-descriptor">jcd-alias</link> name:
- </p>
- <source><![CDATA[
-Implementation odmg = OJB.getInstance();
-Database database = odmg.newDatabase();
-database.open("jcdAliasName#user#password",
Database.OPEN_READ_WRITE);]]></source>
- <p>
- The <em>user</em> and <em>password</em> separated by
<em>#</em> hash only needed, when
- the user/passwd not specified in the connection metadata
(jdbc-connection-descriptor).
+ Please refer to <link
href="site:odmg-guide/lookup-odmg">ODMG-guide</link>.
</p>
</answer>
</faq>
@@ -1256,6 +1187,17 @@
</answer>
</faq>
+ <faq id="open-close-connection">
+ <question>
+ When does OJB open/close a connection?
+ </question>
+ <answer>
+ <p>
+ Please see <link
href="site:connection/open-close-connection">Connection handling guide</link>.
+ </p>
+ </answer>
+ </faq>
+
<faq id="withoutRepository">
<question>
Start OJB without a repository file?
No revision
No revision
1.3.2.10 +24 -1
db-ojb/src/doc/forrest/src/documentation/content/xdocs/site.xml
Index: site.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/site.xml,v
retrieving revision 1.3.2.9
retrieving revision 1.3.2.10
diff -u -r1.3.2.9 -r1.3.2.10
--- site.xml 21 Mar 2005 17:37:52 -0000 1.3.2.9
+++ site.xml 24 Mar 2005 17:54:17 -0000 1.3.2.10
@@ -73,6 +73,7 @@
<lookup-odmg href="#lookupODMG"/>
<api-differences href="#differencesBetweenAPI"/>
<primitive-null href="#primitiveNull"/>
+ <password-needed href="#userPasswordNeeded"/>
</faq>
<javadoc label="Javadoc" href="ext:javadoc" description=""/>
<getting-started label="Getting started" href="getting-started.html"
description="summary of docs"/>
@@ -84,6 +85,7 @@
</mapping-tutorial>
<pb-tutorial label="The PB API" href="pb-tutorial.html"
description="PB tutorial">
<find-by-pk href="#find-by-pk"/>
+ <exception-handling href="#exception-handling"/>
</pb-tutorial>
<odmg-tutorial label="The ODMG API" href="odmg-tutorial.html"
description="odmg tutorial"/>
<jdo-tutorial label="The JDO API" href="jdo-tutorial.html"
description="jdo tutorial"/>
@@ -92,6 +94,13 @@
<guides label="Reference Guides" href="guides/" tab="ref-guides">
<summary label="Summary" href="summary.html"/>
+ <pb-guide label="PB-api guide" href="pb-guide.html">
+ <lookup-pb href="#lookup-pb"/>
+ </pb-guide>
+ <odmg-guide label="ODMG-api guide" href="odmg-guide.html">
+ <no-oql href="#no-oql"/>
+ <lookup-odmg href="#lookup-odmg"/>
+ </odmg-guide>
<platform label="Platform settings" href="platforms.html"
description=""/>
<ojb-properties label="OJB.properties File"
href="ojb-properties.html" description=""/>
<jdbc-types label="JDBC Types" href="jdbc-types.html"
description="">
@@ -107,6 +116,7 @@
<field-descriptor href="#field-descriptor"/>
<custom-attribute href="#custom-attribute"/>
<collection-descriptor href="#collection-descriptor"/>
+ <reference-descriptor href="#reference-descriptor"/>
<query-customizer href="#query-customizer"/>
</repository>
<basic-technique label="Basic Technique"
href="basic-technique.html" description="">
@@ -138,6 +148,9 @@
<extents href="#extents"/>
</advanced-technique>
<query label="OJB queries" href="query.html" description="">
+ <query-by-criteria href="#query-by-criteria"/>
+ <odmg-oql href="#odmg-oql"/>
+ <jdo-oql href="#jdo-oql"/>
<prefetched-relationships href="#prefetched-relationships"/>
</query>
<metadata label="Metadata handling" href="metadata.html"
description="">
@@ -152,6 +165,7 @@
<connection label="Connection handling" href="connection.html"
description="">
<connection-pooling href="#connection-pooling"/>
<obtain-connection href="#obtain-connection"/>
+ <open-close-connection href="#open-close-connection"/>
</connection>
<object-cache label="Caching" href="objectcache.html"
description="">
<distributed-cache href="#distributed-cache"/>
@@ -196,6 +210,7 @@
<external-refs>
<api href="api/">
<javadoc href="index.html"/>
+ <!-- kernel and pb-api classes -->
<metadata-manager
href="org/apache/ojb/broker/metadata/MetadataManager.html"/>
<sequence-manager
href="org/apache/ojb/broker/util/sequence/SequenceManager.html"/>
<jdbc-connection-descriptor
href="org/apache/ojb/broker/metadata/JdbcConnectionDescriptor.html"/>
@@ -218,6 +233,14 @@
<persistence-broker
href="org/apache/ojb/broker/PersistenceBroker.html"/>
<lock-manager
href="org/apache/ojb/broker/locking/LockManager.html"/>
<isolation-level
href="org/apache/ojb/broker/locking/IsolationLevels.html"/>
+ <!-- odmg-api classes -->
+ <odmg-transaction href="org/odmg/Transaction.html"/>
+ <odmg-implementation href="org/odmg/Implementation.html"/>
+ <odmg-oqlquery href="org/odmg/OQLQuery.html"/>
+ <!-- odmg-api extension classes -->
+ <odmg-oqlquery-ext
href="org/apache/ojb/odmg/oql/EnhancedOQLQuery.html"/>
+ <odmg-transaction-ext
href="org/apache/ojb/odmg/TransactionExt.html"/>
+ <odmg-implementation-ext
href="org/apache/ojb/odmg/ImplementationExt.html"/>
</api>
<ojb>
<wiki-page href="http://wiki.apache.org/db-ojb"/>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
