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 2005/04/07 23:55:53 UTC
cvs commit: db-ojb/src/doc/forrest/src/documentation skinconf.xml
arminw 2005/04/07 14:55:53
Modified: src/doc/forrest/src/documentation/content/xdocs/docu/guides
Tag: OJB_1_0_RELEASE advanced-technique.xml
odmg-guide.xml pb-guide.xml platforms.xml
src/doc/forrest/src/documentation/content/xdocs/docu/testing
Tag: OJB_1_0_RELEASE testsuite.xml
src/doc/forrest/src/documentation/content/xdocs/docu/tutorials
Tag: OJB_1_0_RELEASE mapping-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 features.xml site.xml
src/doc/forrest/src/documentation Tag: OJB_1_0_RELEASE
skinconf.xml
Log:
- change pdf page settings, use A4 instead of Letter
- add doc about 'named objects'
- add improvements
Revision Changes Path
No revision
No revision
1.1.2.1 +32 -160 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml
Index: advanced-technique.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/advanced-technique.xml,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- advanced-technique.xml 20 Jun 2004 09:12:33 -0000 1.1
+++ advanced-technique.xml 7 Apr 2005 21:55:52 -0000 1.1.2.1
@@ -1400,6 +1400,7 @@
</p>
</section>
+ <anchor id="callback"/>
<section>
<title>Instance Callbacks</title>
<p>
@@ -1412,71 +1413,16 @@
</p>
<p>
The interface
- <code>org.apache.ojb.PersistenceBrokerAware</code>
+ <link href="ext:pb-aware"><code>org.apache.ojb.PersistenceBrokerAware</code></link>
provides a set of methods that are invoked from the PersistenceBroker
during operations on persistent instances:
</p>
- <source><![CDATA[
-public interface PersistenceBrokerAware
-{
- /**
- * this method is called as the first operation within a call to
- * PersistenceBroker.store(Object pbAwareObject), if
- * the persistent object needs insert.
- */
- public void beforeInsert(PersistenceBroker broker)
- throws PersistenceBrokerException;
-
- /**
- * this method is called as the last operation within a call to
- * PersistenceBroker.store(Object pbAwareObject), if
- * the persistent object needs insert.
- */
- public void afterInsert(PersistenceBroker broker)
- throws PersistenceBrokerException;
-
- /**
- * this method is called as the first operation within a call to
- * PersistenceBroker.store(Object pbAwareObject), if
- * the persistent object needs update.
- */
- public void beforeUpdate(PersistenceBroker broker)
- throws PersistenceBrokerException;
-
- /**
- * this method is called as the last operation within a call to
- * PersistenceBroker.store(Object pbAwareObject), if
- * the persistent object needs update.
- */
- public void afterUpdate(PersistenceBroker broker)
- throws PersistenceBrokerException;
-
- /**
- * this method is called as the first operation within a call to
- * PersistenceBroker.delete(Object pbAwareObject).
- */
- public void beforeDelete(PersistenceBroker broker)
- throws PersistenceBrokerException;
-
- /**
- * this method is called as the last operation within a call to
- * PersistenceBroker.delete(Object pbAwareObject).
- */
- public void afterDelete(PersistenceBroker broker)
- throws PersistenceBrokerException;
-
- /**
- * this method is called as the last operation within a call to
- * PersistenceBroker.getObjectByXXX() or
- * PersistenceBroker.getCollectionByXXX().
- */
- public void afterLookup(PersistenceBroker broker)
- throws PersistenceBrokerException;
-}]]></source>
<p>
- If you want your persistent entity to perform certain operations
- after it has been stored by the PersistenceBroker you have to perform
- the following steps:
+ <strong>Example</strong>
+ </p>
+ <p>
+ If you want that all persistent objects take care of CRUD operations
+ performed by the PersistenceBroker you have to do the following steps:
</p>
<ol>
<li>
@@ -1488,126 +1434,52 @@
</li>
<li>
implement the method
- <code>afterUpdate(PersistenceBroker broker)</code> and
- <code>afterInsert(PersistenceBroker broker)</code> to perform
+ <code>afterUpdate(PersistenceBroker broker)</code>,
+ <code>afterInsert(PersistenceBroker broker)</code> and
+ <code>afterDelete(PersistenceBroker broker)</code> to perform
your intended logic.
</li>
</ol>
<p>
In the following "for demonstration only code" you see a class
- <code>DBAutoIncremented</code>
- that does not use the OJB sequence numbering (more
- <link href="site:sequence-manager">info here</link>),
- but relies on a database specific implementation of autoincremented primary key values.
- <br/>
- When the broker is storing such an instance the DB assigns an autoincrement
- value to the primary key column mapped to the attribute
- <code>m_id</code>.
- The
- <code>afterStore(PersistenceBroker broker)</code> instance callback is used to update
- the the attribute
- <code>m_id</code> with this value.
+ <code>BaseObject</code> (all persistent objects extend this class)
+ that does send a notification using a messenger object after object state change.
</p>
<source><![CDATA[
-public abstract class DBAutoIncremented
- implements PersistenceBrokerAware
+public abstract class BaseObject implements PersistenceBrokerAware
{
- private static final String ID_ATTRIBUTE_NAME = "m_id";
+ private Messenger messenger;
- public void afterDelete(PersistenceBroker broker)
- {
- }
-
- public void afterLookup(PersistenceBroker broker)
+ public void afterInsert(PersistenceBroker broker)
{
+ if(messenger != null)
+ {
+ messenger.send(this.getClass + " Object insert");
+ }
}
-
public void afterUpdate(PersistenceBroker broker)
{
- }
-
- /**
- * after storing a new instance reflect the
- * autoincremented PK value
- * back into the PK attribute.
- */
- public void afterInsert(PersistenceBroker broker)
- {
- try
+ if(messenger != null)
{
- // remove object from cache to ensure we are retrieving a
- // copy that is in sync with the database.
- broker.removeFromCache(this);
-
- Class clazz = getClass();
- ClassDescriptor cld = broker.getClassDescriptor(clazz);
- PersistentField idField = cld
- .getFieldDescriptorByName(ID_ATTRIBUTE_NAME)
- .getPersistentField();
- // retrieve the object again with a query
- // on all non-id attributes.
- Object object =
- broker.getObjectByQuery(
- buildQueryOnAllNonIdAttributes(clazz, cld));
-
- if (object == null)
- {
- throw new PersistenceBrokerException(
- "cannot assign ID to "
- + this
- + " ("
- + clazz
- + ")"
- + " because lookup by attributes failed");
- }
-
- // set id attribute with the value
- // assigned by the database.
- idField.set(this, idField.get(object));
+ messenger.send(this.getClass + " Object update");
}
}
-
- public void beforeDelete(PersistenceBroker broker)
+ public void afterDelete(PersistenceBroker broker)
{
+ if(messenger != null)
+ {
+ messenger.send(this.getClass + " Object deleted");
+ }
}
- public void beforeStore(PersistenceBroker broker)
- {
- }
+ public void afterLookup(PersistenceBroker broker){}
+ public void beforeDelete(PersistenceBroker broker){}
+ public void beforeStore(PersistenceBroker broker){}
- /**
- * returns a query that identifies an object by all its non-
- * primary key attributes.
- * NOTE: This method is only safe, if these values are unique!
- */
- private Query buildQueryOnAllNonIdAttributes(
- Class clazz,
- ClassDescriptor cld)
+ public void setMessenger(Messenger messenger)
{
-
- // note: these are guaranteed to be in the same order
- FieldDescriptor[] fields = cld.getFieldDescriptions();
- Object[] values = cld.getAllValues(this);
- Criteria crit = new Criteria();
-
- for (int i = 0; i < fields.length; i++)
- {
- if (!fields[i].getAttributeName().
- equals(ID_ATTRIBUTE_NAME))
- {
- if (values[i] == null)
- {
- crit.addIsNull(fields[i].getAttributeName());
- }
- else
- {
- crit.addEqualTo(fields[i].getAttributeName(),
- values[i]);
- }
- }
- }
- return QueryFactory.newQuery(clazz, crit);
+ this.messenger = messenger;
}
}]]></source>
</section>
1.1.2.4 +531 -92 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/Attic/odmg-guide.xml
Index: odmg-guide.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/Attic/odmg-guide.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-guide.xml 29 Mar 2005 01:17:01 -0000 1.1.2.3
+++ odmg-guide.xml 7 Apr 2005 21:55:52 -0000 1.1.2.4
@@ -31,21 +31,25 @@
<section>
<title>Introduction</title>
<p>
- The <em>ODMG API</em> is an implementation of the
+ 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 <link href="site:query/odmg-oql">OQL query</link>
+ The ODMG API provides a higher-level API and
+ <link href="site:query/odmg-oql">OQL query</link>
language based interface over the
<link href="site:pb-guide">PersistenceBroker API</link>.
</p>
<p>
- This document is not a <link href="site:odmg-tutorial">ODMG tutorial</link> (newbies please
+ This document is not a
+ <link href="site:odmg-tutorial">ODMG tutorial</link> (newbies please
read the tutorial first) rather than a guide
showing the specific usage and possible pitfalls in handling the ODMG-api and the proprietary
extensions by OJB.
</p>
<p>
If you don't find an answer for a specific question, please have a look at the
- <link href="site:faq">FAQ</link> and the other <link href="site:guides/summary">reference guides</link>.
+ <link href="site:faq">FAQ</link> and the other
+ <link href="site:guides/summary">reference guides</link>.
</p>
</section>
@@ -53,13 +57,17 @@
<section>
<title>Specific Metadata Settings</title>
<p>
- To make OJB's <em>ODMG-api</em> implementation proper work some specific metadata settings
- needed in the <link href="site:repository">repository mapping files</link>.
+ To make OJB's
+ <em>ODMG-api</em> implementation proper work some specific metadata settings
+ needed in the
+ <link href="site:repository">repository mapping files</link>.
</p>
<p>
- All defined <link href="site:repository/reference-descriptor">reference-descriptor</link> and
+ All defined
+ <link href="site:repository/reference-descriptor">reference-descriptor</link> and
<link href="site:repository/collection-descriptor">collection-descriptor</link>
- need specific <em>auto-xxx</em> settings:
+ need specific
+ <em>auto-xxx</em> settings:
</p>
<ul>
<li>
@@ -73,7 +81,8 @@
</li>
</ul>
<p>
- So an example object mapping <link href="site:repository/class-descriptor">class-descriptor</link>
+ So an example object mapping
+ <link href="site:repository/class-descriptor">class-descriptor</link>
look like:
</p>
<source><![CDATA[
@@ -104,12 +113,13 @@
<inverse-foreignkey field-ref="masterId"/>
</collection-descriptor>
...
-</class-descriptor>
- ]]></source>
+</class-descriptor>]]></source>
<p>
A lot of mapping samples can be found in mappings for the
<link href="site:test-suite">OJB test suite</link>. 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>
+ are in
+ <code>repository_junit_odmg.xml</code> file, which can be found under the
+ <em>src/test</em>
directory.
</p>
</section>
@@ -119,7 +129,8 @@
<section>
<title>How to access ODMG-api</title>
<p>
- Obtain a <code>org.odmg.Implementation</code> instance first, then create a new
+ Obtain a
+ <code>org.odmg.Implementation</code> instance first, then create a 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>
@@ -128,11 +139,15 @@
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
+ <em>user</em> and
+ <em>password</em> separated by
+ <em>#</em> hash only needed, when
the user/passwd is not specified in the connection metadata (jdbc-connection-descriptor).
</p>
<p>
- The <link href="site:repository/jdbc-connection-descriptor">jdbc-connection-descriptor</link>
+ The
+ <link href="site:repository/jdbc-connection-descriptor">jdbc-connection-descriptor</link>
may look like:
</p>
<source><![CDATA[
@@ -146,22 +161,30 @@
...
</jdbc-connection-descriptor>]]></source>
<p>
- With method call <code>OJB.getInstance()</code> always a <strong>new</strong>
+ With method call
+ <code>OJB.getInstance()</code> always a
+ <strong>new</strong>
<link href="ext:odmg-implementation">org.odmg.Implementation</link> instance will be created and
- <code>odmg.newDatabase()</code> returns a new <code>Database</code> instance.
+ <code>odmg.newDatabase()</code> returns a new
+ <code>Database</code> instance.
</p>
<p>
For best performance it's recommended to share the
- <link href="ext:odmg-implementation"><code>Implementation</code></link> instance across
- the application. To get the current open database from the <code>Implementation</code> instance,
- use method <code>Implementation.getDatabase(null)</code>
+ <link href="ext:odmg-implementation">
+ <code>Implementation</code>
+ </link> instance across
+ the application. To get the current open database from the
+ <code>Implementation</code> instance,
+ use method
+ <code>Implementation.getDatabase(null)</code>
</p>
<source><![CDATA[
Implementation odmg = ....
// get current used database
Database database = odmg.getDatabase(null);]]></source>
<p>
- Or share the open <code>Database</code> instance as well.
+ Or share the open
+ <code>Database</code> instance as well.
</p>
<p>
See further in FAQ
@@ -174,12 +197,14 @@
<section>
<title>Configuration Properties</title>
<p>
- The OJB <em>ODMG-api</em> implementation has some adjustable properties and pluggable
+ The OJB
+ <em>ODMG-api</em> implementation has some adjustable properties and pluggable
components. All configuration properties can be set in the
<link href="ext:ojb.properties">OJB.properties</link> file.
</p>
<p>
- Here are all properties used by OJB's <em>ODMG-api</em> implementation:
+ Here are all properties used by OJB's
+ <em>ODMG-api</em> implementation:
</p>
<table>
<tr>
@@ -188,22 +213,29 @@
</tr>
<tr>
<td>
+ <anchor id="oql-collection-class"/>
OqlCollectionClass
</td>
<td>
This entry defines the collection type returned
- from <link href="site:query/odmg-oql">OQL queries</link>. By default this
- value is set to a List. This will be good for most situations.
- <br/>
- If you need the additional features of the
- DList interface (DList itself is persistable, support of predicate) change setting
- to the DList implementation (See also property 'DListClass' entry).
+ from
+ <link href="site:query/odmg-oql">OQL queries</link>. By default this
+ value is set to a List implementation. This will be suffice in most situations.
+ <p/>
+ If you want to use the additional features of the
+ DList interface (DList itself is persistable, support of <em>predicates</em>)
+ directly on query results, change setting to the DList implementation
+ (See also property 'DListClass' entry).
<br/>
- Using DLists for large resultsets may be bad for application performance.
- For these scenarios you can use ArrayLists or Vectors.
+ But this will affect the performance - especially for large result sets. So recommended
+ way is create <code>DCollection</code> instances only when needed (e.g. by converting a List
+ result set to a DList).
<br/>
Important note: The collection class to be used MUST implement the
- interface <code>org.apache.ojb.broker.ManageableCollection</code>.
+ interface
+ <link href="site:advanced-technique/manageable-collection">
+ <code>org.apache.ojb.broker.ManageableCollection</code></link>. More info about
+ <link href="site:advanced-technique/manageable-collection">implementing OJB collection types here</link>.
</td>
</tr>
<tr>
@@ -211,7 +243,8 @@
ImplementationClass
</td>
<td>
- Specifies the used base class for the <em>ODMG API</em> implementation. In managed environments
+ Specifies the used base class for the
+ <em>ODMG API</em> implementation. In managed environments
a specific class is needed to potentiate JTA integration of OJB's ODMG implementation.
</td>
</tr>
@@ -229,11 +262,18 @@
cascadingDeleteOneToOne
</td>
<td>
- If set <em>true</em> the cascading delete for 1:1 references will be enabled. This means
+ If set
+ <em>true</em> the cascading delete for 1:1 references will be enabled. This means
that when an object A with 1:1 reference to B will be deleted, B will deleted too and all
1:1 references used by B and so on.
<p/>
- When set <em>false</em> cascading delete is disabled for 1:1 references.
+ When set
+ <em>false</em> cascading delete is disabled for 1:1 references.
+ <note>
+ The recommended setting is <em>false</em>. It is possible to set cascading
+ delete on a <em>per field</em> manner at runtime using
+ <link href="#transaction-ext"><code>Transaction.setCascadingDelete</code></link>.
+ </note>
</td>
</tr>
<tr>
@@ -241,14 +281,25 @@
cascadingDeleteOneToN
</td>
<td>
- If set <em>true</em> the cascading delete for 1:n references will be enabled. This means
+ If set
+ <em>true</em> the cascading delete for 1:n references will be enabled. This means
that when an object A with 1:n reference to B will be deleted, B will deleted too and all
1:n references used by B and so on.
<p/>
- When set <em>false</em> cascading delete is disabled for 1:n references. In this case
- the referenced (<em>n-side</em>) objects will be
- <link href="site:basic-technique/linking"><em>unlinked</em></link> - all FK values of the
- referenced objects will be <em>nullified</em>.
+ When set
+ <em>false</em> cascading delete is disabled for 1:n references. In this case
+ the referenced (
+ <em>n-side</em>) objects will be
+ <link href="site:basic-technique/linking">
+ <em>unlinked</em>
+ </link> - all FK values of the
+ referenced objects will be
+ <em>nullified</em>.
+ <note>
+ The recommended setting is <em>false</em>. It is possible to set cascading
+ delete on a <em>per field</em> manner at runtime using
+ <link href="#transaction-ext"><code>Transaction.setCascadingDelete</code></link>.
+ </note>
</td>
</tr>
<tr>
@@ -256,13 +307,20 @@
cascadingDeleteMToN
</td>
<td>
- If set <em>true</em> the cascading delete for m:n references will be enabled. This means
+ If set
+ <em>true</em> the cascading delete for m:n references will be enabled. This means
that when an object A with m:n reference to B will be deleted, B will deleted too and all
m:n references used by B and so on.
<p/>
- When set <em>false</em> cascading delete is disabled for m:n references. In this case
+ When set
+ <em>false</em> cascading delete is disabled for m:n references. In this case
only the m:n indirection table entries will be deleted, the referenced objects will be
untouched.
+ <note>
+ The recommended setting is <em>false</em>. It is possible to set cascading
+ delete on a <em>per field</em> manner at runtime using
+ <link href="#transaction-ext"><code>Transaction.setCascadingDelete</code></link>.
+ </note>
</td>
</tr>
<tr>
@@ -270,15 +328,18 @@
ImplicitLocking
</td>
<td>
- This property defines the <em>implicit locking</em> behavior. If set to
+ This property defines the
+ <em>implicit locking</em> behavior. If set to
<em>true</em> OJB implicitely locks objects to ODMG
transactions after performing OQL queries or when do a single lock
- on an object using <code>Transaction#lock(...)</code> method.
+ on an object using
+ <code>Transaction#lock(...)</code> method.
<br/>
If implicit locking is used locking objects is recursive, that is
associated objects are also locked.
<p/>
- If ImplicitLocking is set to <em>false</em>, no locks are obtained in OQL
+ If ImplicitLocking is set to
+ <em>false</em>, no locks are obtained in OQL
queries and there is also no recursive locking when do single lock on an object.
</td>
</tr>
@@ -287,12 +348,15 @@
LockAssociations
</td>
<td>
- This property was only used when <em>ImplicitLocking</em> is enabled.
+ This property was only used when
+ <em>ImplicitLocking</em> is enabled.
It defines the behaviour for the OJB implicit locking feature. If set
- to <em>true</em> acquiring a write-lock on a given object x implies write
+ to
+ <em>true</em> acquiring a write-lock on a given object x implies write
locks on all objects associated to x.
<p/>
- If set to <em>false</em>, in any case implicit read-locks are acquired.
+ If set to
+ <em>false</em>, in any case implicit read-locks are acquired.
Acquiring a read- or write lock on x thus allways results in implicit read-locks
on all associated objects.
</td>
@@ -302,7 +366,8 @@
DListClass
</td>
<td>
- The used <code>org.odmg.DList</code> implementation class.
+ The used
+ <code>org.odmg.DList</code> implementation class.
</td>
</tr>
<tr>
@@ -310,7 +375,8 @@
DArrayClass
</td>
<td>
- The used <code>org.odmg.DArray</code> implementation class.
+ The used
+ <code>org.odmg.DArray</code> implementation class.
</td>
</tr>
<tr>
@@ -318,7 +384,8 @@
DMapClass
</td>
<td>
- The used <code>org.odmg.DMap</code> implementation class.
+ The used
+ <code>org.odmg.DMap</code> implementation class.
</td>
</tr>
<tr>
@@ -326,7 +393,8 @@
DBagClass
</td>
<td>
- The used <code>org.odmg.DBag</code> implementation class.
+ The used
+ <code>org.odmg.DBag</code> implementation class.
</td>
</tr>
<tr>
@@ -334,7 +402,8 @@
DSetClass
</td>
<td>
- The used <code>org.odmg.DSet</code> implementation class.
+ The used
+ <code>org.odmg.DSet</code> implementation class.
</td>
</tr>
@@ -346,7 +415,8 @@
<section>
<title>OJB Extensions of ODMG</title>
<p>
- This section describes the propietary extension of the <em>ODMG-api</em>
+ This section describes the propietary extension of the
+ <em>ODMG-api</em>
provided by OJB.
</p>
@@ -354,8 +424,10 @@
<section>
<title>The ImplementationExt Interface</title>
<p>
- The OJB extension of the odmg <link href="ext:odmg-implementation">Implementation</link>
- interface is called <link href="ext:odmg-implementation-ext">ImplementationExt</link>
+ The OJB extension of the odmg
+ <link href="ext:odmg-implementation">Implementation</link>
+ interface is called
+ <link href="ext:odmg-implementation-ext">ImplementationExt</link>
and provide additional methods missed in the standard class definition.
</p>
<ul>
@@ -364,8 +436,11 @@
<br/>
Use this methods to change the used OQL query result class at runtime.
Description can be found in
- <link href="#configuration"><em>Configuration Properties</em></link> section
- and in javadoc of <link href="ext:odmg-implementation-ext">ImplementationExt</link>.
+ <link href="#configuration">
+ <em>Configuration Properties</em>
+ </link> section
+ and in javadoc of
+ <link href="ext:odmg-implementation-ext">ImplementationExt</link>.
</li>
<li>
is/setImpliciteWriteLocks
@@ -373,8 +448,11 @@
Use this methods to change the associated locking type at runtime when implicit
locking is used.
Description can be found in
- <link href="#configuration"><em>Configuration Properties</em></link> section
- and in javadoc of <link href="ext:odmg-implementation-ext">ImplementationExt</link>.
+ <link href="#configuration">
+ <em>Configuration Properties</em>
+ </link> section
+ and in javadoc of
+ <link href="ext:odmg-implementation-ext">ImplementationExt</link>.
</li>
</ul>
</section>
@@ -383,40 +461,48 @@
<section>
<title>The TransactionExt Interface</title>
<p>
- The OJB extension of the odmg <link href="ext:odmg-transaction">Transaction</link> interface is
- called <link href="ext:odmg-transaction-ext">TransactionExt</link> and provide additional
+ The OJB extension of the odmg
+ <link href="ext:odmg-transaction">Transaction</link> interface is
+ called
+ <link href="ext:odmg-transaction-ext">TransactionExt</link> and provide additional
methods missed in the standard class definition.
</p>
<ul>
<li>
markDelete
<br/>
- Description can be found in javadoc of <link href="ext:odmg-transaction-ext">TransactionExt</link>.
+ Description can be found in javadoc of
+ <link href="ext:odmg-transaction-ext">TransactionExt</link>.
</li>
<li>
markDirty
<br/>
- Description can be found in javadoc of <link href="ext:odmg-transaction-ext">TransactionExt</link>.
+ Description can be found in javadoc of
+ <link href="ext:odmg-transaction-ext">TransactionExt</link>.
</li>
<li>
flush
<br/>
- Description can be found in javadoc of <link href="ext:odmg-transaction-ext">TransactionExt</link>.
+ Description can be found in javadoc of
+ <link href="ext:odmg-transaction-ext">TransactionExt</link>.
</li>
<li>
is/setImplicitLocking
<br/>
- Description can be found in javadoc of <link href="ext:odmg-transaction-ext">TransactionExt</link>.
+ Description can be found in javadoc of
+ <link href="ext:odmg-transaction-ext">TransactionExt</link>.
</li>
<li>
setCascadingDelete
<br/>
- Description can be found in javadoc of <link href="ext:odmg-transaction-ext">TransactionExt</link>.
+ Description can be found in javadoc of
+ <link href="ext:odmg-transaction-ext">TransactionExt</link>.
</li>
<li>
getBroker()
<br/>
- Returns the current used broker instance. Usage example is <link href="#pb-access">here</link>.
+ Returns the current used broker instance. Usage example is
+ <link href="#pb-access">here</link>.
</li>
</ul>
</section>
@@ -425,15 +511,18 @@
<section>
<title>The EnhancedOQLQuery Interface</title>
<p>
- The OJB extension of the odmg <link href="ext:odmg-oqlquery">OQLQuery</link> interface is
- called <link href="ext:odmg-oqlquery-ext">EnhancedOQLQuery</link> and provide additional
+ The OJB extension of the odmg
+ <link href="ext:odmg-oqlquery">OQLQuery</link> interface is
+ called
+ <link href="ext:odmg-oqlquery-ext">EnhancedOQLQuery</link> and provide additional
methods missed in the standard class definition.
</p>
<ul>
<li>
create(String queryString, int startAtIndex, int endAtIndex)
<br/>
- Description can be found in javadoc of <link href="ext:odmg-oqlquery-ext">EnhancedOQLQuery</link>.
+ Description can be found in javadoc of
+ <link href="ext:odmg-oqlquery-ext">EnhancedOQLQuery</link>.
</li>
</ul>
</section>
@@ -442,8 +531,11 @@
<section>
<title>Access the PB-api within ODMG</title>
<p>
- As the <link href="site:pb-guide">PB-api</link> was used by OJB's <em>ODMG-api</em>
- implementation, thus it is possible to get access of the used <code>PersistenceBroker</code>
+ As the
+ <link href="site:pb-guide">PB-api</link> was used by OJB's
+ <em>ODMG-api</em>
+ implementation, thus it is possible to get access of the used
+ <code>PersistenceBroker</code>
instance using the extended Transaction interface class
<link href="ext:odmg-transaction-ext">TransactionExt</link>:
</p>
@@ -455,11 +547,13 @@
PersistenceBroker broker = tx.getBroker();
// do work with broker
...
-tx.commit();
- ]]></source>
+tx.commit();]]></source>
<p>
- It's mandatory that the used <em>PersistenceBroker</em> instance <strong>never</strong> be
- closed with a <code>PersistenceBroker.close()</code> call or be committed with
+ It's mandatory that the used
+ <em>PersistenceBroker</em> instance
+ <strong>never</strong> be
+ closed with a
+ <code>PersistenceBroker.close()</code> call or be committed with
<code>PersistenceBroker.commitTransaction()</code>, this will be done internally
by the ODMG implementation.
</p>
@@ -472,9 +566,12 @@
<section>
<title>Transactions</title>
<p>
- The ODMG API uses <em>object-level transactions</em>, compared to the PersistenceBroker
+ The ODMG API uses
+ <em>object-level transactions</em>, compared to the PersistenceBroker
<em>database-level transactions</em>. An ODMG
- <link href="ext:odmg-transaction"><code>Transaction</code></link> instance contains
+ <link href="ext:odmg-transaction">
+ <code>Transaction</code>
+ </link> 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
@@ -503,7 +600,8 @@
<p>
It's possible to configure OJB's ODMG implementation to support implicit locking with
<em>WRITE</em> locks. Then a write lock on an object forces OJB to obtain implicit write locks
- on all referenced objects. See <link href="#configuration">configuration properties</link>.
+ on all referenced objects. See
+ <link href="#configuration">configuration properties</link>.
</p>
</section>
@@ -513,7 +611,8 @@
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 <em>OMG ODMG specification</em>. OJB provides an extension
+ directly through the
+ <em>OMG ODMG specification</em>. OJB provides an extension
to the ODMG specification for instances such as this. Examine this code:
</p>
<source><![CDATA[
@@ -537,6 +636,339 @@
</section>
</section>
+
+ <anchor id="named-objects"/>
+ <section>
+ <title>ODMG Named Objects</title>
+ <p>
+ Using
+ <em>named objects</em> allows to persist all serializable objects under a specified name.
+ The methods to handle
+ <em>named objects</em> are:
+ </p>
+ <source><![CDATA[
+/**
+ * Associate a name with an object and make it persistent.
+ * An object instance may be bound to more than one name.
+ * Binding a previously transient object to a name makes that object persistent.
+ * @param object The object to be named.
+ * @param name The name to be given to the object.
+ * @exception org.odmg.ObjectNameNotUniqueException
+ * If an attempt is made to bind a name to an object and that name is already bound
+ * to an object.
+ */
+public void bind(Object object, String name) throws ObjectNameNotUniqueException;
+
+/**
+ * Lookup an object via its name.
+ * @param name The name of an object.
+ * @return The object with that name.
+ * @exception ObjectNameNotFoundException There is no object with the specified name.
+ * @see ObjectNameNotFoundException
+ */
+public Object lookup(String name) throws ObjectNameNotFoundException;
+
+/**
+ * Disassociate a name with an object
+ * @param name The name of an object.
+ * @exception ObjectNameNotFoundException No object exists in the database with that name.
+ */
+public void unbind(String name) throws ObjectNameNotFoundException;]]></source>
+ <p>
+ To use this feature a internal table and metadata mapping is madatory (by default
+ these settings are enabled in OJB). More information about the needed internal tables
+ see in <link href="site:platform/internal-tables">Platform Guide</link>.
+ </p>
+ <p>
+ If the object to
+ <code>bind</code> is a persistence capable object (the object class is
+ declared in OJB
+ <link href="site:mapping-tutorial">metadata mapping</link>), then the object
+ will be persisted (if needed) dependent on the declared
+ <link href="site:mapping-tutorial">metadata mapping</link>
+ and the
+ <em>named object</em> will be a
+ <strong>link</strong> to the real persisted object.
+ <br/>
+ On
+ <code>unbind</code> of the
+ <em>named object</em> only the link of the persistent object
+ will be removed, the persistent object itself will be untouched.
+ </p>
+ <p>
+ If the object to
+ <code>bind</code> is a serializable non-persistence cacpable object, the object will be
+ serialized and persisted under the specified name.
+ <br/>
+ On
+ <code>unbind</code> the serialized object will be removed.
+ </p>
+
+
+ <anchor id="named-objects-examples"/>
+ <section>
+ <title>Examples</title>
+ <p>
+ In <link href="site:test-suite">OJB test-suite</link> is a test case
+ called <code>org.apache.ojb.odmg.NamedRootsTest</code> which shown similar
+ examples as below, but more detailed.
+ </p>
+
+
+ <anchor id="example_1"/>
+ <p>
+ <strong>1. Persist a serializable object as named object</strong>
+ </p>
+ <p>
+ We want to persist a name list of all planets:
+ </p>
+ <source><![CDATA[
+Transaction tx = odmg.newTransaction();
+tx.begin();
+List planets = new ArrayList();
+example.add("Mercury");
+example.add("Venus");
+example.add("Earth");
+...
+database.bind(planets, "planet-list");
+tx.commit();]]></source>
+ <p>
+ The specified <code>List</code> with all planet names will be serialized
+ and persisted as VARBINARY object.
+ </p>
+ <p>
+ To lookup the persisted list of the solar system planets:
+ </p>
+ <source><![CDATA[
+Transaction tx = odmg.newTransaction();
+tx.begin();
+List planets = (List) database.lookup("planet-list");
+tx.commit();]]></source>
+ <p>
+ To remove the persistent list do:
+ </p>
+ <source><![CDATA[
+Transaction tx = odmg.newTransaction();
+tx.begin();
+database.unbind("planet-list");
+tx.commit();]]></source>
+
+ <anchor id="example_2"/>
+ <p>
+ <strong>2. Persist a persistence capable object as named object</strong>
+ </p>
+ <p>
+ We want to create a <em>named object</em> representing a persistence capable
+ <code>Article</code> object (<code>Article</code> class is declared in OJB
+ <link href="site:mapping-tutorial">metadata mapping</link>):
+ </p>
+ <source><![CDATA[
+Transaction tx = odmg.newTransaction();
+tx.begin();
+// get existing or a new Article object
+Article article = ....
+database.bind(article, "my-article");
+tx.commit();]]></source>
+ <p>
+ OJB first checks if the specified <code>Article</code> object is already persisted - if not
+ it will be persisted. Then based on the
+ <code>Article</code> object
+ <link href="ext:api/identity">
+ <code>Identity</code>
+ </link> the
+ <em>named object</em>
+ will be persisted. So the persistent
+ <em>named object</em> is a link to the persistent real <code>Article</code> object.
+ </p>
+ <p>
+ On lookup of the <em>named object</em> the real <code>Article</code> instance will
+ be returned:
+ </p>
+ <source><![CDATA[
+Transaction tx = odmg.newTransaction();
+tx.begin();
+Article article = (Article) database.lookup("my-article");
+tx.commit();]]></source>
+ <p>
+ On unbind of the <em>named object</em> only the link to the real <code>Article</code> object
+ will be removed, the <code>Article</code> itself will not be touched.
+ <br/>
+ To remove the <code>named object</code> and the <code>Article</code> instance do:
+ </p>
+ <source><![CDATA[
+tx.begin();
+// this only remove the named object link, the Article object
+// itself will not be touched
+database.unbind("my-article");
+// thus delete the object itself too
+database.deletePersistent(article);
+tx.commit();]]></source>
+
+ <anchor id="example_3"/>
+ <p>
+ <strong>3. Persist a collection of persistence capable object as named object</strong>
+ </p>
+ <p>
+ We want to persist a list of the last shown
+ <code>Article</code> objects.
+ The
+ <code>Article</code> class is a persistence capable object (declared in OJB
+ <link href="site:mapping-tutorial">metadata mapping</link>). Thus we don't want
+ to persist a serialized List of <code>Article</code> objects (because the
+ real <code>Article</code> object may change), as shown in
+ <link href="#example_1">example 1</link>, rather we want to persist a List that
+ links to the real persistent <code>Article</code> objects.
+ <br/>
+ This is possible when the ODMG <link href="#dcollections"><code>DCollections</code></link>
+ are used:
+ </p>
+ <source><![CDATA[
+// get the list with last shown Article objects
+List lastArticles = ...
+Transaction tx = odmg.newTransaction();
+tx.begin();
+// obtain new DList instance from Implementation class
+DList namedArticles = odmg.newDList();
+// push Articles to DList
+namedArticles.addAll(lastArticles);
+database.bind(namedArticles, "last-shown");
+tx.commit();
+ ]]></source>
+ <p>
+ In this case OJB first checks for transient
+ <code>Article</code> objects and make
+ these new objects persistent, then based on the
+ <code>Article</code> object
+ <link href="ext:api/identity">
+ <code>Identity</code>
+ </link> the
+ <em>named object</em>
+ will be persisted. So the persistent
+ <em>named object</em> is in this case a list of
+ links to persistent <code>Article</code> objects.
+ </p>
+ <p>
+ On <code>database.lookup("last-shown")</code> the <code>DList</code> will
+ be returned and when access the list entries the <code>Article</code> objects
+ will be materialized.
+ </p>
+ <p>
+ To remove the <em>named object</em> some more attention is needed:
+ </p>
+ <source><![CDATA[
+tx.begin();
+DList namedArticles = ...
+// we want to completely remove the named object
+// the persisted DList with all DList entries,
+// but the Article objects itself shouldn't be deleted:
+// 1. mandatory, clear the list to remove all entries
+namedArticles.clear();
+// 2. unbind named object
+database.unbind("last-shown");
+tx.commit();]]></source>
+ <p>
+ After this the <em>named object</em> will be completely removed, but
+ all <code>Article</code> object will be untouched.
+ </p>
+
+ </section>
+
+ </section>
+
+
+ <anchor id="dcollections"/>
+ <section>
+ <title>ODMG's DCollections</title>
+ <p>
+ The ODMG api declare some specific extensions of the <code>java.util.Collection</code> interface:
+ </p>
+ <ul>
+ <li>
+ <code>org.odmg.DList</code>
+ </li>
+ <li>
+ <code>org.odmg.DSet</code>
+ </li>
+ <li>
+ <code>org.odmg.DBag</code>
+ </li>
+ <li>
+ <code>org.odmg.DMap</code>
+ </li>
+ <li>
+ <code>org.odmg.DArray</code>
+ </li>
+ </ul>
+ <p>
+ The ODMG <link href="ext:odmg-implementation"><code>Implementation</code></link> class
+ provide methods to get new instances of these classes.
+ </p>
+ <p>
+ In OJB all associations between persistence capable classes are declared in the
+ <link href="site:mapping-tutorial">mapping files</link> and <em>1:n and m:n</em> relations
+ can use any collection type class which implement the specific interface
+ <link href="site:advanced-technique/manageable-collection"><code>ManageableCollection</code></link>.
+ <br/>
+ So there is no need to use the ODMG specific collection classes in object relations or when
+ oql-queries are performed (more detailed info see <link href="#oql-collection-class">'oql collection class setting'</link>).
+ </p>
+ <p>
+ One difference to <em>normal</em> collection classes is that <code>DCollection</code> implementation
+ classes are persistence capable classes itself. This means that they can be persisted - e.g. see
+ <link href="#example_3">named objects example</link>. Mandatory is that all containing objects
+ are persistence capable itself.
+ </p>
+ <p>
+ When persisting a <code>DCollection</code> object OJB first lock the collection entries, then the
+ collection itself was locked. On commit the collection entries will be handled in a <em>normal</em>
+ way and for each entry a <em>link object</em> (containing the
+ <link href="ext:identity"><code>Identity</code></link> of the persistence capable object) is persisted.
+ </p>
+ <p>
+ When lookup the persisted <code>DCollection</code> object the <em>link objects</em> are materialized
+ and on access the collection entry will be materialized by the identity.
+ </p>
+ </section>
+
+
+ <anchor id="circular-references"/>
+ <section>
+ <title>Circular- and Bidirectional References</title>
+ <p>
+ The good news, OJB can handle <em>circular-</em> and (as a subset) <em>bidirectional</em> references.
+ But when using foreign keys constraints on the database tables to guarantee referential integrity,
+ you have to pay attention.
+ </p>
+ <p>
+ In OJB <link href="site:test-suite">test-suite</link> a unit test called
+ <code>org.apache.ojb.odmg.CircularTest</code> can be found. The tests show the handling
+ of circular references. The examples shown below are borrowed from this test case.
+ </p>
+
+ <anchor id="circular-examples"/>
+ <section>
+ <title>Examples</title>
+ <p>
+ <strong>Example: Bidirectional 1:1 relation</strong>
+ </p>
+ <p>
+ Class <code>Shop</code> and <code>ShopDetail</code> have a bidirectional
+ <link href="site:basic-technique/one-to-one">1:1 relation</link>. The <code>SHOP</code> table has a foreign
+ key constraint on <code>DETAIL</code> table.
+ </p>
+ <p>
+ ######## TODO #########
+ </p>
+ <p>
+ <strong>Example:Circular 1:1 referenes</strong>
+ </p>
+ <p>
+ ######## TODO #########
+ </p>
+ </section>
+ </section>
+
+
<anchor id="questions"/>
<section>
<title>Questions</title>
@@ -560,7 +992,7 @@
by the ODMG transaction on
<code>tx.commit() / tx.rollback()</code>.
</p>
- <source>
+ <source><![CDATA[
TransactionExt tx = (TransactionExt) odmg.newTransaction();
tx.begin();
....
@@ -575,7 +1007,7 @@
...
tx.commit();
-...</source>
+...]]></source>
<p>
Note: Don't close or commit the used broker instance, this will be done by the odmg-api.
</p>
@@ -588,7 +1020,8 @@
<p>
For each database define a
<link href="site:repository/jdbc-connection-descriptor">jdbc-connection-descriptor</link> same way
- as described in the <link href="site:faq/multiple-databases">FAQ</link>.
+ as described in the
+ <link href="site:faq/multiple-databases">FAQ</link>.
</p>
<p>
Now it is possible to
@@ -596,7 +1029,8 @@
<ul>
<li>
<p>
- access the databases one after another, by closing the current used <code>Database</code>
+ access the databases one after another, by closing the current used
+ <code>Database</code>
instance and by open a new one.
</p>
<source><![CDATA[
@@ -608,15 +1042,19 @@
database = odmg.newDatabase();
database.open("jcdAliasName#user#password", Database.OPEN_READ_WRITE);
...]]></source>
- <p>
- The <code>Database.close()</code> call close the current used <code>Database</code> instance,
+ <p>
+ The
+ <code>Database.close()</code> call close the current used
+ <code>Database</code> instance,
after this it is possible to open a new database instance.
- </p>
+ </p>
</li>
<li>
<p>
- use multiple databases in parallel, by creating a separate <code>Implementation</code>
- and <code>Database</code> instance for each
+ use multiple databases in parallel, by creating a separate
+ <code>Implementation</code>
+ and
+ <code>Database</code> instance for each
<link href="site:repository/jdbc-connection-descriptor">jdbc-connection-descriptor</link>
defined in the mapping metadata.
</p>
@@ -637,7 +1075,8 @@
</ul>
<note>
OJB does not provide distributed transactions by itself. To use distributed transactions,
- OJB have to be <link href="site:deployment/j2ee-server">integrated in an j2ee conform environment</link>
+ OJB have to be
+ <link href="site:deployment/j2ee-server">integrated in an j2ee conform environment</link>
(or made work with an JTA/JTS implementation).
</note>
</section>
1.1.2.3 +40 -1 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/Attic/pb-guide.xml
Index: pb-guide.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/Attic/pb-guide.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-guide.xml 29 Mar 2005 01:17:01 -0000 1.1.2.2
+++ pb-guide.xml 7 Apr 2005 21:55:52 -0000 1.1.2.3
@@ -165,6 +165,45 @@
</p>
</section>
+ <anchor id="listener"/>
+ <section>
+ <title>Hook into OJB - PB-Listener and Instance Callbacks</title>
+ <p>
+ All <em>Listener</em> and instance callback interfaces supported by the
+ <em>PB-api</em> can be used in the
+ top-level API (like <link href="site:odmg-guide">ODMG-api</link>) as well.
+ </p>
+ <p>
+ The OJB Kernel supports three types of "hook" into OJB:
+ </p>
+ <ul>
+ <li>
+ <link href="ext:pb-aware"><code>PersistenceBrokerAware</code></link>
+ <p/>
+ A callback interface used by persistence capable objects (the object class is
+ declared in OJB <link href="site:mapping-tutorial">metadata mapping</link>)
+ to be aware of <code>PersistenceBroker</code> operations on itself.
+ <br/>
+ More detailed information can be found in the
+ <link href="site:advanced-technique/callback">Advanced-Technique Guide</link>.
+ </li>
+ <li>
+ <link href="ext:pb-state-listener"><code>PBStateListener</code></link>
+ <p/>
+ The listener interface for receiving
+ <link href="ext:persistence-broker"><code>PersistenceBroker</code></link> state changes.
+ </li>
+ <li>
+ <link href="ext:pb-lifecycle-listener"><code>PBLifeCycleListener</code></link>
+ <p/>
+ The listener interface for receiving <em>persistent object</em> life cycle information.
+ This interface is intended for non persistent objects which want to
+ track persistent object life cycle. Persistence capable objects can implement
+ <link href="ext:pb-aware"><code>PersistenceBrokerAware</code></link> - see above.
+ </li>
+ </ul>
+ </section>
+
</section>
</body>
1.1.2.2 +83 -19 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.xml
Index: platforms.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- platforms.xml 27 Jul 2004 00:29:31 -0000 1.1.2.1
+++ platforms.xml 7 Apr 2005 21:55:52 -0000 1.1.2.2
@@ -27,7 +27,7 @@
<body>
<section>
- <title>how to use OJB with a specific relational database</title>
+ <title>How to use OJB with a specific relational database</title>
<p>
OJB has been designed to smoothly integrate with any relational
database that provides JDBC support. OJB can be configured to use only JDBC 1.0 API calls
@@ -50,13 +50,18 @@
<section>
<title>Basic Concepts</title>
+ <anchor id="internal-tables"/>
<section>
<title>OJB internal tables</title>
<p>
For certain features OJB relies on several internal tables that must be present in the
- target rdbms to allow a proper functioning.
+ target RDBMS to allow a proper functioning. The associated internal object
+ <link href="site:mapping-tutorial">metadata mapping</link>
+ of these internal used tables can be found in
+ <link href="ext:repository_internal.xml">repository_internal.xml</link> file.
<br/>
- If those features are not needed OJB can be safely run without any internal tables.
+ If those features are not needed/used OJB can be safely run without any internal tables
+ and metadata mapping.
</p>
<p>
The following table
@@ -65,12 +70,23 @@
<table>
<tr>
- <th>Tablename</th>
+ <th>Table</th>
<th>Purpose</th>
</tr>
<tr>
<td>
<code>OJB_HL_SEQ</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_HL_SEQ" description="HIGH/LOW SequenceManager table">
+ <column name="TABLENAME" required="true" primaryKey="true"
+ type="VARCHAR" size="175"/>
+ <column name="FIELDNAME" required="true" primaryKey="true"
+ type="VARCHAR" size="70"/>
+ <column name="MAX_KEY" type="BIGINT"/>
+ <column name="GRAB_SIZE" type="INTEGER"/>
+ <column name="VERSION" type="INTEGER"/>
+</table>]]></source>
</td>
<td>
Table for the high/low sequence manager.
@@ -80,33 +96,40 @@
</tr>
<tr>
<td>
- <code>OJB_LOCKENTRY</code>
- </td>
- <td>
- <p>This table is used to store Object locks if the LockManager is
- run in distributed mode. Not needed in singlevm mode.</p>
- </td>
- </tr>
- <tr>
- <td>
<code>OJB_NRM</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_NRM" description="OJB NAMED ROOTS Table">
+ <column name="NAME" required="true" primaryKey="true"
+ type="VARCHAR" size="250"/>
+ <column name="OID_" type="LONGVARBINARY"/>
+</table>]]></source>
</td>
<td>
<p>The "Named Roots Map". ODMG allows to bind
- persistent objects to an user defined name.
+ persistent objects to an user defined name - called
+ <link href="site:odmg-guide/named-objects"><em>named objects</em></link>.
<br/>The Named roots
map is used to store these bindings. It has NAME (String of
arbitrary length) as primary key and keeps the serialized OID of
- the persistent object in the field OID (String of arbitrary
- length).
+ a persistent object or an arbitrary serialized object in the
+ field OID (String of arbitrary length).
<br/>
- If bind() and lookup() are not used in client apps, this table is not needed
+ If <code>Database.bind(...)</code> and <code>Database.lookup(...)</code>
+ are not used in client apps, this table is not needed.
</p>
</td>
</tr>
<tr>
<td>
<code>OJB_DLIST</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_DLIST" description="DLIST IMPLEMENTATION">
+ <column name="ID" required="true" primaryKey="true"
+ type="INTEGER"/>
+ <column name="SIZE_" type="INTEGER"/>
+</table>]]></source>
</td>
<td>
<p>The table used for the ODMG persistent DList collections.
@@ -118,6 +141,15 @@
<tr>
<td>
<code>OJB_DLIST_ENTRIES</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_DLIST_ENTRIES" description="DList entry table">
+ <column name="ID" required="true" primaryKey="true"
+ type="INTEGER"/>
+ <column name="DLIST_ID" required="true" type="INTEGER"/>
+ <column name="POSITION_" type="INTEGER"/>
+ <column name="OID_" type="LONGVARBINARY"/>
+</table>]]></source>
</td>
<td>
<p>stores the entries of DLists (a wrapper to objects stored in
@@ -130,6 +162,13 @@
<tr>
<td>
<code>OJB_DSET</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_DSET" description="DSET IMPLEMENTATION">
+ <column name="ID" required="true" primaryKey="true"
+ type="INTEGER"/>
+ <column name="SIZE_" type="INTEGER"/>
+</table>]]></source>
</td>
<td>
<p>The table used to store ODMG persistent DSET collections
@@ -141,6 +180,15 @@
<tr>
<td>
<code>OJB_DSET_ENTRIES</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_DSET_ENTRIES" description="DSet entry table">
+ <column name="ID" required="true" primaryKey="true"
+ type="INTEGER"/>
+ <column name="DLIST_ID" required="true" type="INTEGER"/>
+ <column name="POSITION_" type="INTEGER"/>
+ <column name="OID_" type="LONGVARBINARY"/>
+</table>]]></source>
</td>
<td>
<p>This table stores the entries of DSets.
@@ -152,6 +200,13 @@
<tr>
<td>
<code>OJB_DMAP</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_DMAP" description="DMap table">
+ <column name="ID" required="true" primaryKey="true"
+ type="INTEGER"/>
+ <column name="SIZE_" type="INTEGER"/>
+</table>]]></source>
</td>
<td>
<p>The table use to store the ODMG persistent DMap tables
@@ -163,6 +218,15 @@
<tr>
<td>
<code>OJB_DMAP_ENTRIES</code>
+ <br/>
+ <source><![CDATA[
+<table name="OJB_DMAP_ENTRIES" description="DMap entry table">
+ <column name="ID" required="true" primaryKey="true"
+ type="INTEGER"/>
+ <column name="DMAP_ID" required="true" type="INTEGER"/>
+ <column name="KEY_OID" type="VARBINARY"/>
+ <column name="VALUE_OID" type="VARBINARY"/>
+</table>]]></source>
</td>
<td>
<p>The table containing the DMap entries. The Keys and Values of
@@ -199,7 +263,7 @@
<section>
<title>Tables for the regression testbed</title>
<p>
- It is recommended to run the OJB JUnit regression tests
+ It is recommended to run the <link href="site:test-suite">OJB test-suite</link>
against your target database.
Thus you will have to provide several more tables, filled with the proper
testdata.
No revision
No revision
1.1.2.2 +12 -13 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/testing/testsuite.xml
Index: testsuite.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/testing/testsuite.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- testsuite.xml 18 Jan 2005 18:24:53 -0000 1.1.2.1
+++ testsuite.xml 7 Apr 2005 21:55:52 -0000 1.1.2.2
@@ -69,25 +69,24 @@
</p>
<p>
After running the regression tests
- you should see a console output as follows:
+ you should see a console output similar to this:
</p>
<source><![CDATA[
junit-no-compile-no-prepare:
-[junit] Running org.apache.ojb.broker.AllTests
-[junit] Tests run: 382, Failures: 0, Errors: 0, Time elapsed: 50,843 sec
+ [junit] Running org.apache.ojb.broker.AllTests
+ [junit] Tests run: 620, Failures: 0, Errors: 0, Time elapsed: 81,75 sec
+ [junit] Running org.apache.ojb.odmg.AllTests
+ [junit] Tests run: 183, Failures: 0, Errors: 0, Time elapsed: 21,719 sec
+ [junit] Running org.apache.ojb.soda.AllTests
+ [junit] Tests run: 3, Failures: 0, Errors: 0, Time elapsed: 7,641 sec
+ [junit] Running org.apache.ojb.otm.AllTests
+ [junit] Tests run: 79, Failures: 0, Errors: 0, Time elapsed: 28,266 sec
-[junit] Running org.apache.ojb.odmg.AllTests
-[junit] Tests run: 193, Failures: 0, Errors: 0, Time elapsed: 16,243 sec
-
-[junit] Running org.apache.ojb.soda.AllTests
-[junit] Tests run: 3, Failures: 0, Errors: 0, Time elapsed: 8,392 sec
-
-[junit] Running org.apache.ojb.otm.AllTests
-[junit] Tests run: 79, Failures: 0, Errors: 0, Time elapsed: 21,871 sec
+junit-no-compile-no-prepare-selected:
junit-no-compile:
junit:
BUILD SUCCESSFUL
-Total time: 3 minutes 58 seconds]]></source>
+Total time: 3 minutes 26 seconds]]></source>
<p>
We aim at shipping that releases have no failures and errors in the regression tests!
If the Junit tests report errors or failures something does not
No revision
No revision
1.2.2.1 +82 -87 db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/mapping-tutorial.xml
Index: mapping-tutorial.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/mapping-tutorial.xml,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -u -r1.2 -r1.2.2.1
--- mapping-tutorial.xml 21 Jun 2004 21:53:24 -0000 1.2
+++ mapping-tutorial.xml 7 Apr 2005 21:55:52 -0000 1.2.2.1
@@ -30,30 +30,29 @@
<p>
The O/R mapping metadata is the specific configuration information that specifies
how to map classes to relational tables. In OJB this is primarily accomplished
- through an xml document, the <code>repository.xml</code> file, which contains
- all of the initial mapping information.
+ through an xml document, the <link href="site:repository"><code>repository.xml</code></link>
+ file, which contains all of the initial mapping information.
</p>
<section><title>The Product Class</title>
<p>
This tutorial looks at mapping a simple class with no relations:
</p>
<source><![CDATA[
- package org.apache.ojb.tutorials;
+package org.apache.ojb.tutorials;
- public class Product
- {
- /** product name */
- private String name;
-
- /** price per item */
- private Double price;
-
- /** stock of currently available items */
- private int stock;
-
- ...
- }
- ]]></source>
+public class Product
+{
+ /** product name */
+ private String name;
+
+ /** price per item */
+ private Double price;
+
+ /** stock of currently available items */
+ private int stock;
+
+ ...
+}]]></source>
<p>
This class has three fields, <code>price, stock,</code> and <code>name</code>,
that need to be mapped to the database. Additionally, we will introduce one
@@ -61,9 +60,8 @@
artificial key primary id:
</p>
<source><![CDATA[
- /** Artificial primary-key */
- private Integer id;
- ]]></source>
+/** Artificial primary-key */
+private Integer id;]]></source>
<p>
Including the primary-key attribute in the class definition is mandatory,
but under certain conditions <link href="site:howto/anonymous-keys">anonymous keys</link>
@@ -83,14 +81,13 @@
The DDL for such a table, for the <code>Product</code> class might look like:
</p>
<source><![CDATA[
- CREATE TABLE Product
- (
- id INTEGER PRIMARY KEY,
- name VARCHAR(100),
- price DOUBLE,
- stock INTEGER
- )
- ]]></source>
+CREATE TABLE Product
+(
+ id INTEGER PRIMARY KEY,
+ name VARCHAR(100),
+ price DOUBLE,
+ stock INTEGER
+)]]></source>
<p>
The individual field names in the database and class definition match here,
but this is no requirement. They may vary independently of each other as the
@@ -117,30 +114,29 @@
The complete mapping for the <code>Product</code> class is as follows:
</p>
<source><![CDATA[
- <class-descriptor
- class="org.apache.ojb.tutorials.Product"
- table="Product"
- >
- <field-descriptor
- name="id"
- column="id"
- primarykey="true"
- autoincrement="true"
- />
- <field-descriptor
- name="name"
- column="name"
- />
- <field-descriptor
- name="price"
- column="price"
- />
- <field-descriptor
- name="stock"
- column="stock"
- />
- </class-descriptor>
- ]]></source>
+<class-descriptor
+ class="org.apache.ojb.tutorials.Product"
+ table="Product"
+>
+ <field-descriptor
+ name="id"
+ column="id"
+ primarykey="true"
+ autoincrement="true"
+ />
+ <field-descriptor
+ name="name"
+ column="name"
+ />
+ <field-descriptor
+ name="price"
+ column="price"
+ />
+ <field-descriptor
+ name="stock"
+ column="stock"
+ />
+</class-descriptor>]]></source>
<p>
Examine the <code>class-descriptor</code> element. It has two attributes:
</p>
@@ -211,43 +207,42 @@
look like:
</p>
<source><![CDATA[
- package org.apache.ojb.tutorials;
+package org.apache.ojb.tutorials;
+
+/**
+ * @ojb.class
+ */
+public class Product
+{
+ /**
+ * Artificial primary-key
+ *
+ * @ojb.field primarykey="true"
+ * autoincrement="ojb"
+ */
+ private Integer id;
+
+ /**
+ * product name
+ *
+ * @ojb.field length="100"
+ */
+ private String name;
+
+ /**
+ * price per item
+ *
+ * @ojb.field
+ */
+ private Double price;
/**
- * @ojb.class
+ * stock of currently available items
+ *
+ * @ojb.field
*/
- public class Product
- {
- /**
- * Artificial primary-key
- *
- * @ojb.field primarykey="true"
- * autoincrement="ojb"
- */
- private Integer id;
-
- /**
- * product name
- *
- * @ojb.field length="100"
- */
- private String name;
-
- /**
- * price per item
- *
- * @ojb.field
- */
- private Double price;
-
- /**
- * stock of currently available items
- *
- * @ojb.field
- */
- private int stock;
- }
- ]]></source>
+ private int stock;
+}]]></source>
<p>
As you can see, much of the stuff that is present in the descriptor (and the DDL)
is generated automatically by the XDoclet module, e.g. the table/column names and
No revision
No revision
1.1.2.8 +12 -1 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.7
retrieving revision 1.1.2.8
diff -u -r1.1.2.7 -r1.1.2.8
--- faq.xml 29 Mar 2005 01:17:01 -0000 1.1.2.7
+++ faq.xml 7 Apr 2005 21:55:53 -0000 1.1.2.8
@@ -1224,6 +1224,17 @@
</answer>
</faq>
+ <faq id="listener">
+ <question>
+ Hook into OJB - How to add Listener, callback interface?
+ </question>
+ <answer>
+ <p>
+ See <em>Listener/Callback</em> section in <link href="site:pb-guide/listener">PB-Guide</link>.
+ </p>
+ </answer>
+ </faq>
+
<faq id="addPersistentObjects">
<question>
Add new persistent objects metadata (
No revision
No revision
1.1.2.2 +2 -2 db-ojb/src/doc/forrest/src/documentation/content/xdocs/features.xml
Index: features.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/features.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- features.xml 23 Jan 2005 03:09:13 -0000 1.1.2.1
+++ features.xml 7 Apr 2005 21:55:53 -0000 1.1.2.2
@@ -64,7 +64,7 @@
</li>
<li>
Quality assurance taken seriously: More than
- <link href="site:test-suite"><em>600 JUnit-TestCases</em></link> for
+ <link href="site:test-suite"><em>800 JUnit-TestCases</em></link> for
regression tests. JUnit tests integrated into the build scripts.
</li>
<li>
1.3.2.13 +11 -2 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.12
retrieving revision 1.3.2.13
diff -u -r1.3.2.12 -r1.3.2.13
--- site.xml 29 Mar 2005 01:17:01 -0000 1.3.2.12
+++ site.xml 7 Apr 2005 21:55:53 -0000 1.3.2.13
@@ -97,14 +97,18 @@
<pb-guide label="PB-api guide" href="pb-guide.html">
<lookup-pb href="#lookup-pb"/>
<multiple-databases href="#multiple-databases"/>
+ <listener href="#listener"/>
</pb-guide>
<odmg-guide label="ODMG-api guide" href="odmg-guide.html">
<no-oql href="#no-oql"/>
<lookup-odmg href="#lookup-odmg"/>
<metadata href="#metadata"/>
<multiple-databases href="#multiple-databases"/>
+ <named-objects href="#named-objects"/>
</odmg-guide>
- <platform label="Platform settings" href="platforms.html" description=""/>
+ <platform label="Platform settings" href="platforms.html" description="">
+ <internal-tables href="#internal-tables"/>
+ </platform>
<ojb-properties label="OJB.properties File" href="ojb-properties.html" description=""/>
<jdbc-types label="JDBC Types" href="jdbc-types.html" description="">
<jdbc-mapping href="#jdbc-mapping"/>
@@ -149,6 +153,7 @@
<types-for-associations href="#types-for-associations"/>
<which-collection-type href="#which-collection-type"/>
<extents href="#extents"/>
+ <callback href="#callback"/>
</advanced-technique>
<query label="OJB queries" href="query.html" description="">
<query-by-criteria href="#query-by-criteria"/>
@@ -236,6 +241,10 @@
<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"/>
+ <pb-lifecycle-listener href="org/apache/ojb/broker/PBLifeCycleListener.html"/>
+ <pb-state-listener href="org/apache/ojb/broker/PBStateListener.html"/>
+ <pb-aware href="org/apache/ojb/broker/PersistenceBrokerAware.html"/>
+
<!-- odmg-api classes -->
<odmg-transaction href="org/odmg/Transaction.html"/>
<odmg-implementation href="org/odmg/Implementation.html"/>
No revision
No revision
1.1.2.3 +5 -5 db-ojb/src/doc/forrest/src/documentation/skinconf.xml
Index: skinconf.xml
===================================================================
RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/skinconf.xml,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -u -r1.1.2.2 -r1.1.2.3
--- skinconf.xml 1 Oct 2004 15:08:10 -0000 1.1.2.2
+++ skinconf.xml 7 Apr 2005 21:55:53 -0000 1.1.2.3
@@ -327,7 +327,7 @@
portrait).
Supported text alignments are left, right, justify (default left).
-->
- <page size="letter" orientation="portrait" text-align="left"/>
+ <page size="a4" orientation="portrait" text-align="left"/>
<!--
Margins can be specified for top, bottom, inner, and outer
@@ -338,10 +338,10 @@
Specified below are the default settings.
-->
<margins double-sided="false">
- <top>1in</top>
- <bottom>1in</bottom>
- <inner>1.25in</inner>
- <outer>1in</outer>
+ <top>0.2in</top>
+ <bottom>0.2in</bottom>
+ <inner>0.8in</inner>
+ <outer>0.8in</outer>
</margins>
<!--
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: cvs commit: db-ojb/src/doc/forrest/src/documentation skinconf.xml
Posted by Martin Kalén <mk...@apache.org>.
arminw@apache.org wrote:
> Log:
> - change pdf page settings, use A4 instead of Letter
> - add doc about 'named objects'
> - add improvements
Great work!
Kudos also to Brian, Tom and all others that have made previous efforts
to shape up the docs.
One day I will get Forrest running here and change the Oracle LOB sections...
(That are currently documenting stuff that was present when the dinosaurs
used OJB during the jurassic period...) ;)
Cheers,
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org