db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs site.xml
Date Mon, 19 Dec 2005 16:54:52 GMT
arminw      2005/12/19 08:54:52

  Modified:    src/doc/forrest/src/documentation/content/xdocs/docu/guides
                        Tag: OJB_1_0_RELEASE advanced-technique.xml
                        sequencemanager.xml
               src/doc/forrest/src/documentation/content/xdocs Tag:
                        OJB_1_0_RELEASE site.xml
  Log:
  update mapping part 3
  
  Revision  Changes    Path
  No                   revision
  No                   revision
  1.1.2.10  +125 -127  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.2.9
  retrieving revision 1.1.2.10
  diff -u -r1.1.2.9 -r1.1.2.10
  --- advanced-technique.xml	18 Dec 2005 02:14:38 -0000	1.1.2.9
  +++ advanced-technique.xml	19 Dec 2005 16:54:51 -0000	1.1.2.10
  @@ -749,17 +749,17 @@
       </reference-descriptor>
   </class-descriptor>]]></source>
                   <p>
  -                    The mapping for the base class <code>Employee</code> is
ordinary and we using
  -                    an <a href="site:repository/autoincrement"><em>autoincrement</em></a>
primary key field.
  +                    The mapping for base class <code>Employee</code> is ordinary
and we using
  +                    a <a href="site:repository/autoincrement"><em>autoincrement</em></a>
primary key field.
                       <br/>
  -                    In the sub-classes <code>Executive</code> and <code>Manager</code>
it's not allowed
  +                    In the subclasses <code>Executive</code> and <code>Manager</code>
it's not allowed
                       to use <em>autoincrement</em> primary keys, because OJB
will automatically copy the
  -                    primary keys of the base class to all sub-classes.
  +                    primary keys of the base class to all subclasses.
                   </p>
                   <p>
                       As you can see this mapping needs a special
                       <a href="site:repository/reference-descriptor">reference-descriptor</a>
  -                    in the sub-classes <code>Executive</code> and <code>Manager</code>
that advises OJB to load
  +                    in the subclasses <code>Executive</code> and <code>Manager</code>
that advises OJB to load
                       the values for the inherited attributes from the super-class by a <em>JOIN</em>
using the
                       foreign key reference.
                  <br/>
  @@ -798,151 +798,149 @@
       CONSORTIUM_KEY  INT
   )]]></source>
                   <p>
  -                    Attributes from the base- or super-class or can be used the same way
as attributes
  -                    of the target class when querying e.g. for <code>Manager</code>.
  -                    No <a href="site:query/joins">path-expression</a> is needed
in this case:
  +                    Attributes from the base- or superclasses can be used the same way
as attributes
  +                    of the target class when querying - e.g. for <code>Executive</code>
or <code>Manager</code>.
  +                    No <a href="site:query/joins">path-expression</a> is needed
in this case. The following
  +                    examples returns all <code>Executive</code> and <code>Manager</code>
matching the criteria:
                   </p>
                   <source><![CDATA[
   Criteria c = new Criteria();
  +// attribute defined in base class Employee
   c.addEqualTo("name", "Kent");
  +// attribute defined in Executive
   c.addEqualTo("department", "press");
   Query q = QueryFactory.newQuery(Executive.class, c);
  -broker.getCollectionByQuery(q);]]></source>
  -                <p>
  -                    ####### TODO: update docs for 1.0.4 #####
  -                </p>
  -                <p>
  -                    The above example is based on the assumption that the primary key attribute
  -                    <code>B.id</code> and its underlying column
  -                    <code>B_TABLE.ID</code>
  -                    is also used as the foreign key attribute.
  -                </p>
  -                <p>
  -                    Now let us consider a case where
  -                    <code>B_TABLE</code> contains an additional
  -                    foreign key column
  -                    <code>B_TABLE.A_ID</code> referencing
  -                    <code>A_TABLE.ID</code>.
  -                    In this case the layout for class
  -                    <code>B</code> could look like follows:
  -                </p>
  -                <source><![CDATA[
  -public class B extends A
  -{
  -    // id is the primary key
  -    int id;
  -
  -    // aID is the foreign key referencing A.id
  -    int aID;
  +// returns all matching Executive and Manager instances
  +Collection result = broker.getCollectionByQuery(q);]]></source>
   
  -    // mapped to a column in B_TABLE
  -    int someValueFromB;
  -}]]></source>
  +                <anchor id="per-subclass-using-fk"/>
  +                <section>
  +                    <title>Table Per Subclass via Foreign Key</title>
                   <p>
  -                    The mapping for
  -                    <code>B</code> will then look like follows:
  -                </p>
  -                <source><![CDATA[
  -<class-descriptor
  -  class="org.apache.ojb.broker.B"
  -  table="B_TABLE"
  ->
  -  <field-descriptor
  -     name="id"
  -     column="ID"
  -     jdbc-type="INTEGER"
  -     primarykey="true"
  -     autoincrement="true"
  -  />
  -
  -  <field-descriptor
  -     name="aID"
  -     column="A_ID"
  -     jdbc-type="INTEGER"
  -  />
  -
  -  <field-descriptor
  -     name="someValueFromB"
  -     column="VALUE_"
  -     jdbc-type="INTEGER"
  -  />
  -
  -  <reference-descriptor name="super"
  -       class-ref="org.apache.ojb.broker.A">
  -     <foreignkey field-ref="aID" />
  -  </reference-descriptor>
  -</class-descriptor>]]></source>
  -                <p>
  -                    The mapping now contains an additional field-descriptor for the
  -                    <code>aID</code> attribute.
  +                    The above example is based on the assumption that the
  +                    <a href="site:repository/primary-key">primary key</a> attribute
  +                    <code>Employee.id</code> and its underlying column
  +                    <code>EMPLOYEE.ID</code> is also used as the foreign key
attribute in the
  +                    the subclasses.
                   </p>
                   <p>
  -                    In the
  -                    <code>"super"</code> reference-descriptor the foreignkey
  -                    <code>field-ref</code> attribute
  -                    had to be changed to
  -                    <code>"aID"</code>.
  +                    Now let us consider a case where this is not possible, then it's possible
  +                    to use an additional foreign key field/column in the subclass referencing
  +                    the base-/superclass.
                   </p>
                   <p>
  -                    It is also possible to have the extra
  -                    foreign key column
  -                    <code>B_TABLE.A_ID</code> but without having a
  -                    foreign key attribute in class
  -                    <code>B</code>:
  -                </p>
  -                <source><![CDATA[
  -public class B extends A
  -{
  -    // id is the primary key
  -    int id;
  -
  -    // mapped to a column in B_TABLE
  -    int someValueFromB;
  -}]]></source>
  -                <p>
  -                    We can use OJB's anonymous field feature to get everything working
without the
  -                    <code>"aID"</code> attribute. We keep the field-descriptor
for aID, but declare it as an
  -                    anonymous field.
  +                    In this case the layout for class <code>Executive</code>
would need an
  +                    additional field <code>employeeFk</code> to store the foreign
key reference
  +                    to <code>Employee</code>.
  +                    <br/>
  +                    To avoid the additional field in the subclass (if desired) we can use
OJB's
  +                    <a href="site:advanced-technique/anonymous-keys">anonymous field
feature</a>
  +                    to get everything working without the <code>employeeFk</code>
attribute in subclass
  +                    <code>Employee</code> (thus the <a href="#classes-inheritance-example">java
classes</a> of our
  +                    <a href="#mapping-inheritance-example">mapping example</a>).
We keep the
  +                    <a href="site:repository/field-descriptor">field-descriptor</a>
for <code>employeeFk</code>,
  +                    but declare it as an <em>anonymous field</em>.
                       We just have to add an attribute
  -                    <code>access="anonymous"</code> to the field-descriptor:
  +                    <code>access="anonymous"</code> to the new field-descriptor
<code>employeeFk</code>:.
                   </p>
                   <source><![CDATA[
   <class-descriptor
  -  class="org.apache.ojb.broker.B"
  -  table="B_TABLE"
  +    class="Employee"
  +    table="EMPLOYEE"
   >
  -  <field-descriptor
  -     name="id"
  -     column="ID"
  -     jdbc-type="INTEGER"
  -     primarykey="true"
  -     autoincrement="true"
  -  />
  +    <field-descriptor
  +        name="id"
  +        column="ID"
  +        jdbc-type="INTEGER"
  +        primarykey="true"
  +        autoincrement="true"
  +    />
  +    <field-descriptor
  +        name="name"
  +        column="NAME"
  +        jdbc-type="VARCHAR"
  +    />
  +</class-descriptor>
   
  -  <field-descriptor
  -     name="aID"
  -     column="A_ID"
  -     jdbc-type="INTEGER"
  -     access="anonymous"
  -  />
  +<class-descriptor
  +    class="Executive"
  +    table="EXECUTIVE"
  +>
  +    <field-descriptor
  +        name="id"
  +        column="ID"
  +        jdbc-type="INTEGER"
  +        primarykey="true"
  +        autoincrement="true"
  +    />
  +    <field-descriptor
  +        name="department"
  +        column="DEPARTMENT"
  +        jdbc-type="VARCHAR"
  +    />
  +    <field-descriptor
  +        name="employeeFk"
  +        column="EMPLOYEE_FK"
  +        jdbc-type="INTEGER"
  +        access="anonymous"
  +    />
  +    <reference-descriptor name="super"
  +        class-ref="Employee"
  +    >
  +        <foreignkey field-ref="employeeFk"/>
  +    </reference-descriptor>
  +</class-descriptor>
   
  -  <field-descriptor
  -     name="someValueFromB"
  -     column="VALUE_"
  -     jdbc-type="INTEGER"
  -  />
  +<class-descriptor
  +    class="Manager"
  +    table="MANAGER"
  +>
  +    <field-descriptor
  +        name="id"
  +        column="ID"
  +        jdbc-type="INTEGER"
  +        primarykey="true"
  +        autoincrement="true"
  +    />
  +    <field-descriptor
  +        name="consortiumKey"
  +        column="CONSORTIUM_KEY"
  +        jdbc-type="INTEGER"
  +    />
   
  -  <reference-descriptor name="super"
  -       class-ref="org.apache.ojb.broker.A">
  -     <foreignkey field-ref="aID" />
  -  </reference-descriptor>
  +    <field-descriptor
  +        name="executiveFk"
  +        column="EXECUTIVE_FK"
  +        jdbc-type="INTEGER"
  +        access="anonymous"
  +    />
   
  +    <reference-descriptor name="super"
  +        class-ref="Executive"
  +    >
  +        <foreignkey field-ref="executiveFk"/>
  +    </reference-descriptor>
   </class-descriptor>]]></source>
                   <p>
  -                    You can learn more about the anonymous fields feature in this
  -                    <a href="site:howto/anonymous-keys">howto</a> and how
  -                    it <a href="#anonymous-keys">work here</a>.
  +                    Now it's possible to use <em>autoincrement</em> primary
key fields in all classes
  +                    of the hierarchy (because they are decoupled from the inheritance references).
  +                    <br/>
  +                    The <em>foreignkey</em>-element have to refer the new (anomymous)
  +                    foreign-key field.
                   </p>
  +                    <warning>
  +                        The used primary keys (compound or single) have to unique over
the mapped class
  +                        hierarchy to avoid object identity conflicts. Else it could happen
e.g. when
  +                        searching for a <code>Employee</code> with id="42"
OJB maybe find a
  +                        <code>Employee</code> and a <code>Executive</code>
object with id="42"!.
  +                        <br/>
  +                        Thus it's problematic to use a
  +                        <a href="site:sequence-manager/identity-columns">database
idenity columns</a> based
  +                        <a href="site:sequence-manager">sequence-manager</a>.
In this case it's mandatory to use
  +                        a different value scope (start index of identity column) for each
class in hierarchy
  +                        (e.g. 1 for Employee, 1000000000 for Executive, ...).
  +                    </warning>
  +                    </section>
               </section>
           </section>
   
  
  
  
  1.1.2.10  +3 -3      db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml
  
  Index: sequencemanager.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml,v
  retrieving revision 1.1.2.9
  retrieving revision 1.1.2.10
  diff -u -r1.1.2.9 -r1.1.2.10
  --- sequencemanager.xml	14 Dec 2005 01:19:19 -0000	1.1.2.9
  +++ sequencemanager.xml	19 Dec 2005 16:54:51 -0000	1.1.2.10
  @@ -104,7 +104,7 @@
                   <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="#native">Identity column supporting sequence manager</a>),
because the
  +                    <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.
  @@ -577,7 +577,7 @@
                   </section>
   
   
  -                <anchor id="native"/>
  +                <anchor id="identity-columns"/>
                   <section>
                       <title>Database Identity-column based sequence manager</title>
                       <p>
  
  
  
  No                   revision
  No                   revision
  1.3.2.24  +4 -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.23
  retrieving revision 1.3.2.24
  diff -u -r1.3.2.23 -r1.3.2.24
  --- site.xml	18 Dec 2005 02:14:38 -0000	1.3.2.23
  +++ site.xml	19 Dec 2005 16:54:51 -0000	1.3.2.24
  @@ -201,7 +201,9 @@
                   <turn-off-caching href="#turn-off-caching"/>
                   <oscache href="#oscache"/>
               </object-cache>
  -            <sequence-manager label="Sequence manager" href="sequencemanager.html"/>
  +            <sequence-manager label="Sequence manager" href="sequencemanager.html">
  +                <identity-columns href="#identity-columns"/>
  +            </sequence-manager>
               <logging label="Logging" href="logging.html"/>
               <lock-manager label="Locking" href="lockmanager.html">
                   <distributed-locking href="#distributed-locking"/>
  
  
  

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


Mime
View raw message