Return-Path: 
 <ojb-dev-return-14104-apmail-db-ojb-dev-archive=db.apache.org@db.apache.org>
Delivered-To: apmail-db-ojb-dev-archive@www.apache.org
Received: (qmail 92044 invoked from network); 17 Aug 2006 16:15:22 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 17 Aug 2006 16:15:22 -0000
Received: (qmail 16479 invoked by uid 500); 17 Aug 2006 16:15:21 -0000
Delivered-To: apmail-db-ojb-dev-archive@db.apache.org
Received: (qmail 16461 invoked by uid 500); 17 Aug 2006 16:15:21 -0000
Mailing-List: contact ojb-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
List-Unsubscribe: <mailto:ojb-dev-unsubscribe@db.apache.org>
List-Help: <mailto:ojb-dev-help@db.apache.org>
List-Post: <mailto:ojb-dev@db.apache.org>
List-Id: "OJB Developers List" <ojb-dev.db.apache.org>
Reply-To: "OJB Developers List" <ojb-dev@db.apache.org>
Delivered-To: mailing list ojb-dev@db.apache.org
Received: (qmail 16450 invoked by uid 500); 17 Aug 2006 16:15:21 -0000
Received: (qmail 16447 invoked by uid 99); 17 Aug 2006 16:15:21 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 17 Aug 2006 09:15:21 -0700
X-ASF-Spam-Status: No, hits=-9.4 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME
X-Spam-Check-By: apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Received: from [140.211.166.113] (HELO eris.apache.org) (140.211.166.113)
    by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 17 Aug 2006 09:15:20 -0700
Received: by eris.apache.org (Postfix, from userid 65534)
	id 5A24B1A981A; Thu, 17 Aug 2006 09:15:00 -0700 (PDT)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r432275 -
 /db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml
Date: Thu, 17 Aug 2006 16:14:59 -0000
To: ojb-commits@db.apache.org
From: arminw@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20060817161500.5A24B1A981A@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Author: arminw
Date: Thu Aug 17 09:14:58 2006
New Revision: 432275

URL: http://svn.apache.org/viewvc?rev=432275&view=rev
Log:
fix OJB-96

Modified:
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml

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?rev=432275&r1=432274&r2=432275&view=diff
==============================================================================
--- 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 Thu Aug 17 09:14:58 2006
@@ -97,10 +97,10 @@
                 <section>
                     <title>since OJB 1.0.4</title>
                     <p>
-                        OJB no longer assign the PK values of transient objects on creation of
-                        the <a href="ext:identity"><code>Identity</code></a> objects (using
+                        OJB no longer assign the PK values of <strong>transient objects</strong> on creation of
+                        <a href="ext:identity"><code>Identity</code></a> objects (using
                         <a href="ext:identity-factory"><code>IdentityFactory</code></a>).
-                        The <code>Identity</code> object of a transient persistence capable object
+                        The <code>Identity</code> object of a <em>transient persistence capable object</em>
                         is completely independent of the "real" primary key assigned on insert
                         of the object - when calling
                     </p>
@@ -108,7 +108,7 @@
 Identity oid = broker.serviceIdentity().buildIdentity(object);]]></source>
                     <p>
                         the specified persistence capable object will not be modified and the
-                        returned <code>Identity</code> object use transient primary key placeholder.
+                        returned <code>Identity</code> object use <em>transient primary key placeholders</em>.
                     </p>
                     <p>
                         The reason for doing this was to "harmonize" the behavior of OJB when
@@ -118,9 +118,23 @@
                         it's not possible to lookup the generated PK value before
                         the object is written to database.
                     </p>
-                    <p>
-                        
-                    </p>
+
+                    <anchor id="forceBackward"/>
+                    <section>
+                        <title>Backward compatibility: Force the assignment of PK fields while Identity creation</title>
+                        <p>
+                            To be backward compatible with older versions of OJB it's still possible to force the
+                            assignment of PK fields while Identity creation before the object was made persistent,
+                            using the an specific Identity constructor (instead of the
+                            <code>IdentityFactory</code> described in above sections).
+                        </p>
+                        <source><![CDATA[
+Identity oid = new Identity(object, broker);]]></source>
+                        <note>
+                            But it's strongly recommended to avoid these calls to avoid the drawbacks described above.
+                            This call will be illegal in future versions of OJB.
+                        </note>
+                    </section>
                 </section>
 
                 <anchor id="before-1.0.4"/>
@@ -130,25 +144,28 @@
                     By default OJB triggers the computation
                     of unique ids during calls to PersistenceBroker.store(...).
                     Sometimes it will be necessary to have the ids computed in advance,
-                    before a new persistent object was written to database.
+                    <strong>before</strong> a new persistent object was written to database.
                     This can be done by simply obtaining the Identity of the respective object as
                     follows:
                 </p>
                 <source><![CDATA[
-Identity oid = broker.serviceIdentity().buildIdentity(object);]]></source>
+Identity oid = broker.serviceIdentity().buildIdentity(object);
+or
+Identity oid = new Identity(object, broker);]]></source>
                 <p>
                     This creates an <a href="ext:api/identity"><code>Identity</code></a> object for the
-                    new persistent object and set all primary key values of the new persistent object
-                    - But it only works if <a href="#autoincrement"><code>autoincrement</code></a>
+                    transient object and set all primary key values. But this only works if
+                    <a href="#autoincrement"><code>autoincrement</code></a>
                     is enabled for the primary key fields.
                 </p>
                 <warning>
                     Force computation of unique values is not allowed when using <em>database based
                     Identity columns</em> for primary key generation (e.g via
                     <a href="#identity-columns">Identity column supporting sequence manager</a>), because the
-                    <em>real</em> PK value is at the earliest available after database insert operation. If you
-                    nevertheless force PK computing, OJB will use an temporary dummy PK value in the
-                    Identity object and this may lead to unexpeted behavior.
+                    <em>real</em> PK value is at the earliest available after database insert operation
+                    (never for transient objects). If you
+                    nevertheless force PK computing, OJB will use temporary dummy PK values in the
+                    transient object and created Identity instance - this may lead to unexpeted behavior.
                 </warning>
                 <p>
                     Info about lookup persistent objects by primary key fields



---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org