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 Wed, 09 Mar 2005 15:23:05 GMT
arminw      2005/03/09 07:23:05

  Modified:    src/doc/forrest/src/documentation/content/xdocs/docu/guides
                        Tag: OJB_1_0_RELEASE jdbc-types.xml repository.xml
                        sequencemanager.xml
               src/doc/forrest/src/documentation/content/xdocs Tag:
                        OJB_1_0_RELEASE site.xml
  Log:
  update sequence manager docs
  
  Revision  Changes    Path
  No                   revision
  No                   revision
  1.1.2.1   +21 -21    db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/jdbc-types.xml
  
  Index: jdbc-types.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/jdbc-types.xml,v
  retrieving revision 1.1
  retrieving revision 1.1.2.1
  diff -u -r1.1 -r1.1.2.1
  --- jdbc-types.xml	20 Jun 2004 09:12:33 -0000	1.1
  +++ jdbc-types.xml	9 Mar 2005 15:23:05 -0000	1.1.2.1
  @@ -32,12 +32,19 @@
           <section>
               <title>Mapping of JDBC Types to Java Types</title>
               <p>
  -                OJB implements the mapping conventions for JDBC and Java types as specified by
  -                the JDBC 3.0 specification.
  -                <br/>
  -                See the table below for details.
  +                OJB implements the mapping conversions for JDBC and Java types as specified by
  +                the JDBC 3.0 specification (see JDBC 3.0 specification
  +                <em>Appendix B, Data Type Conversion Tables</em>). See the
  +                <link href="#mapping-table">table below</link> for details.
               </p>
  -
  +            <p>
  +                If a sql-java type mapping is needed, that doesn't match the java types defined by
  +                the specification, e.g. a field in the persistent object class is of type <em>int[]</em>
  +                and the DB type is <em>VARCHAR</em> or a <em>List</em> field have to be mapped to
  +                <em>VARCHAR</em> a <link href="#field-conversion">field-conversion</link>
  +                class can be used.
  +            </p>
  +            <anchor id="mapping-table"/>
               <table>
                   <tr>
                       <th>JDBC Type</th>
  @@ -160,15 +167,15 @@
   
           <anchor id="field-conversion"/>
           <section>
  -            <title>Type and Value Conversions</title>
  +            <title>Type and Value Conversions - The <code>FieldConversion</code> Interface</title>
   
               <section>
                   <title>Introduction</title>
                   <p>
                       A typical problem with O/R tools is mismatching datatypes: a
  -                    class from the domain model has an attribute of type boolean but the
  +                    class from the domain model has an attribute of type <em>boolean</em> but the
                       corresponding database table stores this attribute in a column of
  -                    type bit or int.
  +                    type <em>BIT</em> or int.
                   </p>
                   <p>
                       This example explains how OJB allows you to define
  @@ -339,10 +346,10 @@
                   <p>
                       Coming back to our example,
                       there is only one thing left to do: we must tell OJB to use the proper
  -                    FieldConversion for the Article class. This is done in the XML
  -                    Repository. The field-descriptor allows to define a
  -                    <code>conversion</code>
  -                    attribute declaring the fully qualified FieldConversion class:
  +                    <em>FieldConversion</em> for the <em>Article</em> class. This is done in the XML
  +                    repository file. The <link href="site:repository/field-descriptor">field-descriptor</link>
  +                    allows to define a <em>conversion</em> attribute declaring the fully qualified
  +                    <em>FieldConversion</em> class:
                   </p>
   
                   <source><![CDATA[
  @@ -352,21 +359,14 @@
            proxy="dynamic"
            table="Artikel"
      >
  -      <extent-class class-ref="org.apache.ojb.broker.BookArticle" />
  -      <extent-class class-ref="org.apache.ojb.broker.CdArticle" />
  -
         ...
  -
         <field-descriptor
            name="isSelloutArticle"
            column="Auslaufartikel"
            jdbc-type="INTEGER"
  -         conversion="org.apache.ojb.broker.accesslayer.
  -                        conversions.Boolean2IntFieldConversion"
  +         conversion="org.apache.ojb.broker.accesslayer.conversions.Boolean2IntFieldConversion"
         />
  -
         ...
  -
      </class-descriptor>]]></source>
               </section>
           </section>
  
  
  
  1.1.2.3   +2 -1      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.2
  retrieving revision 1.1.2.3
  diff -u -r1.1.2.2 -r1.1.2.3
  --- repository.xml	19 Feb 2005 21:49:53 -0000	1.1.2.2
  +++ repository.xml	9 Mar 2005 15:23:05 -0000	1.1.2.3
  @@ -31,6 +31,7 @@
   
       <body>
   
  +        <anchor id="introduction"/>
           <section>
               <title>Introduction - repository syntax</title>
               <p>
  
  
  
  1.1.2.3   +317 -228  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.2
  retrieving revision 1.1.2.3
  diff -u -r1.1.2.2 -r1.1.2.3
  --- sequencemanager.xml	4 Oct 2004 15:00:13 -0000	1.1.2.2
  +++ sequencemanager.xml	9 Mar 2005 15:23:05 -0000	1.1.2.3
  @@ -32,10 +32,9 @@
           <section>
               <title>The OJB Sequence Manager</title>
               <p>
  -                All sequence manager implementations you will find under the
  -                <code>org.apache.ojb.broker.util.sequence</code> package using the following naming
  -                convention
  -                <code>SequenceManagerXXXImpl</code>.
  +                All <link href="ext:sequence-manager">sequence manager</link> implementations shipped with OJB
  +                you can find under the <code>org.apache.ojb.broker.util.sequence</code> package using the
  +                following naming convention <code>SequenceManagerXXXImpl</code>.
               </p>
   
               <anchor id="autoincrement"/>
  @@ -43,12 +42,10 @@
                   <title>Automatical assignment of unique values</title>
                   <p>
                       As mentioned in
  -                    <link href="site:mapping-tutorial">mapping tutorial</link> OJB provides a mechanism to automatic
  -                    assign unique values for primary key attributes. You just have to enable the
  -                    <code>autoincrement</code> attribute in the respective
  -                    <link href="site:repository/field-descriptor">
  -                        <em>FieldDescriptor</em>
  -                    </link>
  +                    <link href="site:mapping-tutorial">mapping tutorial</link> OJB provides a mechanism to
  +                    automatic assign unique values for primary key attributes. You just have to enable the
  +                    <strong><em>autoincrement</em></strong> attribute in the respective
  +                    <link href="site:repository/field-descriptor"><em>field-descriptor</em></link>
                       of the XML repository file as follows:
                   </p>
                   <source><![CDATA[
  @@ -80,8 +77,8 @@
   
                   <p>
                       This mechanism works for all whole-numbered column types like BIGINT, INTEGER, SMALLINT,...
  -                    and for CHAR, VARCHAR coliumns. This mechanism helps you to keep your business logic free
  -                    from code that computes unique Ids for primary key attributes.
  +                    and for CHAR, VARCHAR columns. This mechanism helps you to keep your business logic free
  +                    from code that computes unique ID's for primary key attributes.
                   </p>
               </section>
   
  @@ -123,17 +120,14 @@
                   <title>How to change the sequence manager?</title>
                   <p>
                       To enable a specific
  -                    <code>SequenceManager</code> implementation declare
  -                    an
  -                    <code>sequence-manager</code> within the
  -                    <code>jdbc-connection-descriptor</code>
  -                    element in the
  -                    <link href="site:repository">repository file</link>.
  -                    If no
  -                    <code>sequence-manager</code> was specified in the
  -                    <code>jdbc-connection-descriptor</code>,
  -                    OJB use a default sequence manager implementation (default was
  -                    <em>SequenceManagerHighLowImpl</em>).
  +                    <link href="ext:sequence-manager"><code>SequenceManager</code></link> implementation declare
  +                    an <em>sequence-manager</em> attribute within the
  +                    <link href="site:jdbc-connection-descriptor">jdbc-connection-descriptor</link>
  +                    element in the <link href="site:repository">repository file</link>.
  +                    <br/>
  +                    If no <em>sequence-manager</em> was specified in the
  +                    <em>jdbc-connection-descriptor</em>, OJB use a default sequence manager implementation
  +                    (default was <em>SequenceManagerHighLowImpl</em>).
                   </p>
                   <p>
                       Further information you could find in the
  @@ -141,8 +135,8 @@
                   </p>
                   <p>
                       Example
  -                    <code>jdbc-connection-descriptor</code> using
  -                    <code>sequence-manager</code> tag:
  +                    <em>jdbc-connection-descriptor</em> using
  +                    a <em>sequence-manager</em> tag:
                   </p>
                   <source><![CDATA[
   <jdbc-connection-descriptor
  @@ -157,29 +151,27 @@
           password=""
           batch-mode="false"
       >
  -        <connection-pool
  -            maxActive="5"
  -            whenExhaustedAction="0"
  -            validationQuery="select count(*) from OJB_HL_SEQ"
  -        />
  -
  -        <sequence-manager className="org.apache.ojb.broker.util.
  -                                    sequence.SequenceManagerHighLowImpl">
  -            <attribute attribute-name="grabSize" attribute-value="5"/>
  -            <attribute attribute-name="globalSequenceId"
  -                    attribute-value="false"/>
  -            <attribute attribute-name="globalSequenceStart"
  -                    attribute-value="10000"/>
  -        </sequence-manager>
  +
  +    <connection-pool
  +        maxActive="5"
  +        whenExhaustedAction="0"
  +        validationQuery="select count(*) from OJB_HL_SEQ"
  +    />
  +
  +    <sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl">
  +        <attribute attribute-name="grabSize" attribute-value="5"/>
  +        <attribute attribute-name="globalSequenceId" attribute-value="false"/>
  +        <attribute attribute-name="globalSequenceStart" attribute-value="10000"/>
  +    </sequence-manager>
   </jdbc-connection-descriptor>]]></source>
                   <p>
                       The mandatory
  -                    <code>className</code> attribute needs the full-qualified class name of the
  -                    desired sequence-manager implementation. If a implementation needs configuration
  +                    <em>className</em> attribute needs the <strong>full-qualified class name</strong>
  +                    of the desired sequence-manager implementation. If a implementation needs configuration
                       properties you pass them using
  -                    <code>attribute</code> tags with
  -                    <code>attribute-name</code> represents the property name and
  -                    <code>attribute-value</code>
  +                    <link href="site:repository/custom-attribute">custom attribute</link> tags with
  +                    <em>attribute-name</em> represents the property name and
  +                    <em>attribute-value</em>
                       the property value. Each sequence manager implementation shows all properties on
                       the according javadoc page.
                   </p>
  @@ -190,11 +182,10 @@
                   <title>SequenceManager implementations</title>
                   <p>
                       Source code of all
  -                    <code>SequenceManager</code> implementations can be
  -                    found in
  -                    <code>org.apache.ojb.broker.util.sequence</code> package.
  +                    <link href="ext:sequence-manager">SequenceManager</link> implementations can be
  +                    found in <code>org.apache.ojb.broker.util.sequence</code> package.
                       <br/>
  -                    If you still think something is missing you can just write your
  +                    If you still think something is missing, you can just write your
                       <link href="#how-to-write">own</link>
                       sequence manager implementation.
                   </p>
  @@ -203,25 +194,24 @@
                   <section>
                       <title>High/Low sequence manager</title>
                       <p>
  -                        Per default OJB internally uses a High/Low algorithm based sequence manager
  -                        for the generation of unique ids, as described in
  -                        <link href="ext:ambysoft">
  -                            Mapping Objects To Relational Databases</link>.
  -                        <br/>
  -                        This implementation is called
  +                        The <link href="ext:sequence-manager">sequence manager</link> implementation class
                           <code>ojb.broker.util.sequence.SequenceManagerHighLowImpl</code>
  -                        and is able to generate IDs unique to a given object and
  -                        all extent objects declarated in the objects class descriptor.
  +                        and is able to generate ID's unique to a given object and
  +                        all <link href="site:advanced-technique/extents"><em>extent</em> objects</link> declarated in the
  +                        objects class descriptor.
                           <br/>
  -                        If you ask for an uid using an interface with several
  +                        If you ask for an ID using an interface with several
                           implementor classes, or a baseclass with several subclasses the returned
  -                        uid have to be unique accross all tables representing objects of the
  -                        extent in question (more see
  -                        <link href="#extent-aware">here</link>).
  +                        ID have to be unique accross all tables representing objects of the
  +                        interface or base class (more see <link href="#extent-aware">here</link>).
                           <br/>
                           It's also possible to use this implementation in a
  -                        <em>global mode</em>, generate
  -                        global unique id's.
  +                        <em>global mode</em>, generate global unique id's.
  +                    </p>
  +                    <p>
  +                        This implementation needs an internal database table and object mapping declaration
  +                        to persist the used sequences (see
  +                        <link href="site:repository/introduction">OJB internal mapping</link> for more info).
                       </p>
                       <source><![CDATA[
   <sequence-manager className=
  @@ -235,43 +225,42 @@
   </sequence-manager>]]></source>
                       <p>
                           With property
  -                        <code>grabSize</code> you set the size of the assigned ids
  -                        (default was 20).
  +                        <code>grabSize</code> you set the size of the assigned ID's kept
  +                        in memory for each <em>autoincrement</em> field. If the assigned ID's
  +                        are exhausted a database call is made to lookup the next bunch
  +                        of ID's (default <em>grabSize</em> is 20).
  +                        <br/>
  +                        If OJB was shutdown/redeployed all unused assigned ID's are lost.
                       </p>
                       <p>
                           The attribute
                           <code>sequenceStart</code> define the start value of the
  -                        id generation (default was '0').
  +                        id generation (default was '1'). It's recommended to use start values
  +                        greater than '0' to avoid problems with primitive primary key fields.
                       </p>
                       <p>
                           If property
                           <code>globalSequenceId</code> was set
                           <code>true</code> you will
  -                        get global unique ids over all persistent objects. Default was
  +                        get global unique ID's over all persistent objects. Default was
                           <code>false</code>.
  -                        <br/>
  +                    </p>
  +                    <p>
                           The attribute
                           <code>globalSequenceStart</code> define the start value of the
  -                        global id generation (default was 10000). <em>(Deprecated use property
  -                        'sequenceStart' instead)</em>
  +                        global id generation (default was 10000). <em>This property is deprecated, please use
  +                        property 'sequenceStart' instead</em>.
                       </p>
                       <p>
  -                        This sequence manager implementation supports user defined
  -                        <em>sequence-names</em>
  -                        to manage the sequences.
  -                        The attribute
  -                        <code>autoNaming</code> define if sequence names should be build
  -                        automatic if none found in
  -                        <code>field-descriptor</code>.
  +                        This sequence manager implementation supports <em>user defined
  +                        sequence-names</em> as well as <em>automatic generated sequence-names</em>
  +                        to manage the sequences - more about
  +                        <link href="#sequence-name"><em>sequence-names</em> here</link>.
                           <br/>
  -                        If set 'true' OJB try to build a
  -                        sequence name automatic if none found in field-descriptor
  -                        and set this name as
  -                        <code>sequence-name</code>
  -                        in field-descriptor (see
  -                        <link href="#sequence-name">more</link>).
  -                        If set 'false' OJB throws an exception
  -                        if none sequence name was found in field-descriptor (default was 'true').
  +                        The attribute <code>autoNaming</code> can be used to enable <em>auto-generation</em>
  +                        of <em>sequence-names</em>, default value is <em>true</em>.
  +                        <br/>
  +                        More info about attribute <link href="#auto-naming"><em>autoNaming</em> here</link>.
                       </p>
                       <p>
                           Limitations:
  @@ -296,39 +285,37 @@
                           called
                           <code>ojb.broker.util.sequence.SequenceManagerInMemoryImpl</code>.
                           <br/>
  -                        Only the first time an uid was requested for a object,
  +                        Only the first time an UID was requested for a object,
                           the manager query the database for the max value of the target
                           column - all following request were performed in memory. This
  -                        implementation ditto generate unique ids across all
  -                        extents, using the same mechanism as the High/Low implementation.
  +                        implementation ditto generate unique ID's across all
  +                        <link href="site:advanced-technique/extents"><em>extents</em></link>,
  +                        using the same mechanism as the High/Low sequence manager implementation.
                       </p>
                       <source><![CDATA[
  -<sequence-manager className="org.apache.ojb.broker.util.
  -                                sequence.SequenceManagerInMemoryImpl">
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerInMemoryImpl">
       <attribute attribute-name="sequenceStart" attribute-value="0"/>
       <attribute attribute-name="autoNaming" attribute-value="true"/>
   </sequence-manager>]]></source>
                       <p>
                           The attribute
                           <code>sequenceStart</code> define the start value of the
  -                        id generation (default was '0').
  +                        id generation (default was '1'). It's recommended to use start values
  +                        greater than '0' to avoid problems with primitive primary key fields.
                       </p>
                       <p>
  -                        For attribute
  -                        <code>autoNaming</code>
  -                        <link href="#high-low">see</link>
  -                    </p>
  -                    <p>
  -                        This sequence manager implementation supports user defined
  -                        <em>sequence-names</em>
  -                        to manage the sequences (see
  -                        <link href="#sequence-name">more</link>) or if not
  -                        set in
  -                        <code>field-descriptor</code> it is done automatic.
  +                        This sequence manager implementation supports <em>user defined
  +                        sequence-names</em> as well as <em>automatic generated sequence-names</em>
  +                        to manage the sequences - more about <link href="#sequence-name">sequence-names</link>.
  +                        <br/>
  +                        The attribute <code>autoNaming</code> can be used to enable <em>auto-generation</em>
  +                        of <em>sequence-names</em>, default value is <em>true</em>.
  +                        <br/>
  +                        More info about <link href="#auto-naming">autoNaming</link>.
                       </p>
                       <p>
  -                        This is the fastest standard sequence manager implementation, but
  -                        has some Limitations:
  +                        This is the fastest standard sequence manager implementation and should work
  +                        with all databases without any specific preparation, but has some Limitations:
                           <br/>- do not use in clustered environments
                           <br/>- superfluously to mention, do not use (or handle with care) if other non-OJB
                           applications insert objects too
  @@ -340,64 +327,57 @@
                   <section>
                       <title>Database sequences based implementation</title>
                       <p>
  -                        If your database support sequence key generation (e.g. Oracle, SAP DB, PostgreSQL)
  -                        you could use the
  -                        <code>SequenceManagerNextValImpl</code> implementation let
  -                        your database generate the requested ids.
  +                        If your database support sequence key generation (e.g. Oracle, SAP DB, PostgreSQL, ...)
  +                        you can use the <code>SequenceManagerNextValImpl</code> implementation to force generation
  +                        of the sequence keys by your database.
                       </p>
                       <source><![CDATA[
  -<sequence-manager className="org.apache.ojb.broker.util.
  -                                sequence.SequenceManagerNextValImpl">
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerNextValImpl">
       <attribute attribute-name="autoNaming" attribute-value="true"/>
   </sequence-manager>]]></source>
                       <p>
  +                        Database based sequences (sequence objects, sequence generators) are special
  +                        (single-row) tables in the database created with an specific statement,
  +                        e.g. <code>CREATE SEQUENCE sequenceName</code>. This implementation use database
  +                        based sequences to assign ID's in <em>autoincrement fields</em>.
  +                        <br/>
  +                        The sequences can be managed by hand, by a database tool or by OJB. If the <em>autoNaming</em>
  +                        attribute is enabled OJB creates sequences if needed. Also it's possible to declare <em>sequence names</em>
  +                        in the <link href="site:repository/field-descriptor">field-descriptor</link>
  +                    </p>
  +                    <p>
                           Attribute
  -                        <code>autoNaming</code> default was 'true'. If set 'true' OJB try to build a
  -                        sequence name automatic if none found in field-descriptor
  -                        and set this generated name as
  -                        <code>sequence-name</code>
  -                        in field-descriptor.
  -                        <br/>
  -                        If set 'false' OJB throws an exception
  -                        if none sequence name was found in field-descriptor, ditto
  -                        OJB does NOT try to create a database sequence entry when
  -                        for given sequence name no database sequence could be found.
  -                    </p>
  -                    <anchor id="sequence-name"/>
  -                    <p>
  -                        When using this sequence manager it is possible
  -                        to define a
  -                        <strong>sequence-name</strong>
  -                        <code>field-descriptor</code> attribute
  -                        in the repository file for each autoincrement/pk field. If you don't
  -                        specify a sequence name, the sequence manager try to
  -                        build a extent-aware sequence name on its own - except you set attribute
  -                        <code>autoNaming</code> to 'false', then an exception will be thrown.
  -                        <br/>
  -                        Keep in mind that in this case you are responsible to be aware of extents.
  -                        Thus you have to use the same
  -                        <code>sequence-name</code> attribute value
  -                        for all extents, even if the extents were mapped to different database tables.
  -                        <br/>
  -                        See usage of the
  -                        <code>sequence-name</code> attribute:
  +                        <code>autoNaming</code>, default setting is <em>true</em>. If set <em>true</em> OJB will
  +                        try to auto-generate a sequence name if none was found in
  +                        <link href="site:repository/field-descriptor">field-descriptor's</link>
  +                        <em>sequence-name</em> attribute and create a database sequence if needed - more
  +                        details see <link href="#auto-naming">autoNaming</link> section.
  +                        <br/>
  +                        The auto-generated name will be set as
  +                        <link href="#sequence-name"><em>sequence-name</em></link> in the <em>field-descriptor</em>.
  +                        <br/>
  +                        If set <em>false</em> OJB throws an exception
  +                        if none <em>sequence-name</em> was found in <em>field-descriptor</em>, also
  +                        OJB does NOT try to create a database sequence when
  +                        for a given sequence name (specified in <em>field-descriptor</em>) no database sequence
  +                        can be found.
                       </p>
                       <source><![CDATA[
   <class-descriptor
  -      class="org.apache.ojb.broker.sequence.SMDatabaseSequence"
  -      table="SM_TAB_DATABASE_SEQUENCE"
  -    >
  -        <field-descriptor
  -         name="seqId"
  -         column="SEQ_ID"
  -         jdbc-type="INTEGER"
  -         primarykey="true"
  -         autoincrement="true"
  -         sequence-name="TEST_SEQUENCE"
  -        />
  +    class="org.greatest.software.Person"
  +    table="GS_PERSON"
  +>
  +    <field-descriptor
  +        name="seqId"
  +        column="SEQ_ID"
  +        jdbc-type="INTEGER"
  +        primarykey="true"
  +        autoincrement="true"
  +        sequence-name="PERSON_SEQUENCE"
  +    />
   
  -        ....
  -    </class-descriptor>]]></source>
  +....
  +</class-descriptor>]]></source>
                       <p>
                           Limitations:
                           <br/>- none known
  @@ -409,29 +389,36 @@
                   <section>
                       <title>Database sequences based high/low implementation</title>
                       <p>
  -                        Based on the sequence manager implementation described above, but
  +                        Based on the sequence manager implementation described
  +                        <link href="#database-sequences-based">above</link>, but
                           use a high/low algorithm to avoid database access.
                       </p>
                       <source><![CDATA[
  -<sequence-manager className="org.apache.ojb.broker.util.
  -                        sequence.SequenceManagerSeqHiLoImpl">
  -<attribute attribute-name="grabSize" attribute-value="20"/>
  -<attribute attribute-name="autoNaming" attribute-value="true"/>
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerSeqHiLoImpl">
  +    <attribute attribute-name="grabSize" attribute-value="20"/>
  +    <attribute attribute-name="autoNaming" attribute-value="true"/>
   </sequence-manager>]]></source>
                       <p>
  -                        With the property
  -                        <code>grabSize</code> you set the size of the assigned ids.
  -                        For attribute
  -                        <code>autoNaming</code>
  -                        <link href="#database-sequences-based">see</link>.
  +                        With property
  +                        <code>grabSize</code> you set the size of the assigned ID's kept
  +                        in memory for each <em>autoincrement</em> field. If the assigned ID's
  +                        are exhausted a database call is made to lookup the next bunch
  +                        of ID's using the next database sequence (default <em>grabSize</em> is 20).
  +                        <br/>
  +                        If OJB was shutdown/redeployed all unused assigned ID's are lost.
  +                    </p>
  +                    <p>
  +                        Attribute
  +                        <link href="#auto-naming"><em>autoNaming</em></link>
  +                        is the same as for <link href="#database-sequences-based">SequenceManagerNextValImpl</link>.
                       </p>
                       <p>
                           This sequence manager implementation supports user defined
                           <em>sequence-names</em>
                           to manage the sequences (see
                           <link href="#sequence-name">more</link>) or if not
  -                        set in
  -                        <code>field-descriptor</code> it is done automatic.
  +                        set in <code>field-descriptor</code> it is done automatic when
  +                        <link href="#auto-naming">autoNaming</link> is enabled.
                       </p>
                       <p>
                           Limitations:
  @@ -500,25 +487,19 @@
                           Last, enable this sequence manager implementation:
                       </p>
                       <source><![CDATA[
  -<sequence-manager className="org.apache.ojb.broker.util.
  -                       sequence.SequenceManagerStoredProcedureImpl">
  -    <attribute attribute-name="autoNaming"
  -                                    attribute-value="true"/>
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerStoredProcedureImpl">
  +    <attribute attribute-name="autoNaming" attribute-value="true"/>
   </sequence-manager>]]></source>
                       <p>
  -                        For attribute
  -                        <link href="#high-low">
  -                            <em>autoNaming</em>
  -                            see
  -                        </link>.
  +                        For attribute <link href="#auto-naming"><em>autoNaming</em> see</link>.
                       </p>
                       <p>
                           This sequence manager implementation supports user defined
                           <em>sequence-names</em>
                           to manage the sequences (see
                           <link href="#sequence-name">more</link>) or if not
  -                        set in
  -                        <code>field-descriptor</code> it is done automatic.
  +                        set in <code>field-descriptor</code> it is done automatic when
  +                        <link href="#auto-naming">autoNaming</link> is enabled.
                       </p>
                       <p>
                           Limitations:
  @@ -550,13 +531,12 @@
                       </p>
                       <source><![CDATA[
   <field-descriptor
  -         name="guid"
  -         column="document_file_guid"
  -         jdbc-type="VARCHAR"
  -         primarykey="true"
  -         autoincrement="true"
  -      />
  -                        ]]></source>
  +    name="guid"
  +    column="document_file_guid"
  +    jdbc-type="VARCHAR"
  +    primarykey="true"
  +    autoincrement="true"
  +/>]]></source>
                       <p>
                           Note that the jdbc-type is a VARCHAR,  and thus the attribute (in this case
                           'guid') on your class should be a String (SQL Server does the conversion
  @@ -569,8 +549,7 @@
                           jdbc-connection-descriptor like this:
                       </p>
                       <source><![CDATA[
  -<sequence-manager
  -    className="org.apache.ojb.broker.util.sequence.SequenceManagerMSSQLGuidImpl"
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerMSSQLGuidImpl"
   />
                           ]]></source>
                       <p>
  @@ -588,12 +567,12 @@
                   <section>
                       <title>Identity based sequence manager</title>
                       <p>
  -                        This sequence manager implementation supports database Identity columns
  +                        This sequence manager implementation supports database <em>Identity columns</em>
                           (supported by MySQL, MsSQL, HSQL, ...). When using identity columns we have to do
                           a trick to make the sequence manager work.
                           <br/>
                           OJB identify each persistence capable object by a unique
  -                        ojb-Identity object. These ojb-Identity
  +                        <link href="ext:identity">ojb-Identity object</link>. These ojb-Identity
                           objects were created using the sequence manager instance to
                           get UID's. Often these ojb-Identity objects were created before
                           the persistence capable object was written to database.
  @@ -604,9 +583,9 @@
                           generated UID. Thus in SequenceManagerNativeImpl we have to do a trick and use
                           a 'temporary' UID till the object was written to database.
                           <br/>
  -                        So, if it's possible try to avoid using Identity columns in your
  -                        database model. If not use this sequence manager implementation to
  -                        as a workaround for the Identity problem.
  +                        So for best compatibility try to avoid using <em>Identity columns</em> in your
  +                        database model. If this is not possible, use this sequence manager implementation to
  +                        work with database <em>Identity columns</em>.
                       </p>
                       <p>
                           To enable this sequence manager implementation set in your
  @@ -618,11 +597,18 @@
   </sequence-manager>
                           ]]></source>
                       <p>
  -                        To declare the identity column in the repository.xml file add
  +                        To declare the identity column in the persistent class mapping
  +                        <link href="site:repository/class-descriptor">class-descriptor</link>, add the
  +                        following attributes to the primary key/identity key
  +                        <link href="site:repository/field-descriptor">field-descriptor</link>:
  +                        <br/>
                           <code>primarykey="true"</code>,
                           <code>autoincrement="true"</code> and
  -                        <code>access="readonly"</code> to the field-descriptor
  -                        for your table's primary key identity column.
  +                        <strong><code>access="readonly"</code></strong>
  +                        <br/>
  +                        The first and second attributes are the same as all sequence manager implementations
  +                        use to support autoincrement PK fields, the third one is mandatory for database
  +                        <em>Identity columns</em> only.
                       </p>
                       <source><![CDATA[
   <field-descriptor
  @@ -636,7 +622,7 @@
                       <p>
                           Limitations:
                           <br/>- The Identity columns have to
  -                        <strong>start with value >= 1</strong> and should
  +                        <strong>start with value greater than '0'</strong> and should
                           never be negative.
                           <br/>- Use of Identity columns is
                           <strong>not extent aware</strong> (This may change in further versions).
  @@ -644,6 +630,96 @@
                           <link href="#extent-aware">here</link>.
                       </p>
                   </section>
  +
  +
  +                <anchor id="sequence-name"/>
  +                <section>
  +                    <title>The <em>sequence-name</em> attribute</title>
  +                    <p>
  +                        Several <link href="ext:sequence-manager">SequenceManager</link> implementations
  +                        using <em>sequences</em> (synonyms: <em>sequence objects</em>, <em>sequence generators</em>)
  +                        to manage the ID generation. Sequences are <em>entities</em> which generate unique ID's using
  +                        e.g. database table per sequence, database row per sequence or an in-memory java-object.
  +                        <br/>
  +                        To address the sequences, each <em>sequence</em> has an unique <em>sequence-name</em>.
  +                   </p>
  +                   <p>
  +                        In OJB the sequence-name of an autoincrement field is declared
  +                        in a <em>sequence-name</em> attribute within the
  +                        <link href="site:repository/field-descriptor">field-descriptor</link>.
  +                    </p>
  +                    <source><![CDATA[
  +<class-descriptor
  +    class="org.greatest.software.Person"
  +    table="GS_PERSON"
  +>
  +    <field-descriptor
  +        name="id"
  +        column="ID_PERSON"
  +        jdbc-type="INTEGER"
  +        primarykey="true"
  +        autoincrement="true"
  +        sequence-name="PERSON_SEQUENCE"
  +    />
  +
  +....
  +</class-descriptor>]]></source>
  +                    <p>
  +                        The <em>sequence-name</em> attribute in the <em>field-descriptor</em> is only
  +                        needed if the used sequence manager supports sequences, the field should be
  +                        <em>autoincremented</em> and the auto-assign of a sequence-name is not desired.
  +                    </p>
  +                    <note>
  +                        Each <em>sequence-name</em> has be <link href="#extent-aware">extent-aware</link>.
  +                    </note>
  +                    <p>
  +                        If you don't specify a sequence name in the <em>field-descriptor</em> it is possible
  +                        to auto-assign a sequence-name by OJB if <link href="#auto-naming">autoNaming</link>
  +                        is supported by the used sequence manager implementation.
  +                    </p>
  +
  +                </section>
  +
  +                <anchor id="auto-naming"/>
  +                <section>
  +                    <title>The <em>autoNaming</em> property</title>
  +                    <p>
  +                        All shipped <link href="ext:sequence-manager">SequenceManager</link> implementations
  +                        using <em>sequences</em> for ID generation support a property
  +                        called <em>autoNaming</em> which can be declared as a
  +                        <link href="site:repository/custom-attribute"><em>custom attribute</em></link>
  +                        within the <em>sequence-manager</em> element:
  +                    </p>
  +                    <source><![CDATA[
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerNextValImpl">
  +    <attribute attribute-name="autoNaming" attribute-value="true"/>
  +</sequence-manager>]]></source>
  +                    <p>
  +                        If set <em>true</em> OJB try to build a
  +                        <em>sequence name</em> by it's own (a simple algorithm was used to auto-generate
  +                        the sequence name - more details how it works in
  +                        <link href="#pitfalls">pitfalls section</link>)
  +                        and set this name as <code>sequence-name</code>
  +                        in the <link href="site:repository/field-descriptor">field-descriptor</link> of
  +                        the autoincrement field if no <link href="#sequence-name">sequence name</link>
  +                        is specified.
  +                        <br/>
  +                        If set <em>false</em> the sequence manager throw an exception
  +                        if a <em>sequence name</em> can't be found or was not declared in the
  +                        <em>field-descriptor</em> of the autoincrement field.
  +                        In this case OJB expects a valid <em>sequence-name</em> in the <em>field-descriptor</em>.
  +                        <br/>
  +                        If the attribute <code>autoNaming</code> is set <em>false</em> the sequence manager
  +                        never try to auto-generate a <em>sequence-name</em> (more detailed info
  +                        <link href="#no-auto-build">here</link>). If set <em>true</em> and a <em>sequence-name</em>
  +                        is set in the <em>field-descriptor</em>, the <em>SequenceManager</em> will use this one and
  +                        does <strong>not</strong> override the existing one.
  +                    </p>
  +                    <p>
  +                        The default setting is <em>true</em>.
  +                    </p>
  +                </section>
  +
               </section>
   
   
  @@ -677,11 +753,11 @@
                       If your sequence manager implementation was derived from
                       <code>org.apache.ojb.broker.util.sequence.AbstractSequenceManager</code>
                       it's easy to pass configuration properties to your implementation using
  -                    <code>attribute</code> tags.
  +                    <link href="site:repository/custom-attribute"><em>custom attributes</em></link>.
                   </p>
                   <source><![CDATA[
   <sequence-manager className="my.SequenceManagerMYImpl">
  -<attribute attribute-name="myProperty" attribute-value="test"/>
  +    <attribute attribute-name="myProperty" attribute-value="test"/>
   </sequence-manager>]]></source>
                   <p>
                       With
  @@ -708,13 +784,14 @@
                       <title>When using sequence-name attribute in field-descriptor?</title>
                       <p>
                           Most
  -                        <code>SequenceManager</code> implementations based on sequence names.
  +                        <code>SequenceManager</code> implementations based on
  +                        <link href="#sequence-name">sequence names</link>.
                           If you want retain control of sequencing use your own
                           <code>sequence-name</code> attribute
                           in the
                           <code>field-descriptor</code>. In that case you are reponsible to use the same name
  -                        across extents (see more info about
  -                        <link href="site:advanced-technique/polymorphism">extents and polymorphism</link>).
  +                        across extents, we call it <link href="#extent-aware">extent-aware</link> (see more
  +                        info about <link href="site:advanced-technique/polymorphism">extents and polymorphism</link>).
                           Per default the sequence manager build its own
                           <em>extent aware</em> sequence name with an
                           simple algorithm
  @@ -733,6 +810,7 @@
                   </section>
   
   
  +                <anchor id="extent-aware"/>
                   <section>
                       <title>What to hell does
                           <em>extent aware</em> mean?
  @@ -744,18 +822,17 @@
                           <code>Cat</code>
                           which extend
                           <code>Animal</code>. For each non-abstract class we create a separate
  -                        database table.
  +                        database table and
  +                        <link href="site:advanced-technique/polymorphism">declare the inheritance</link> in OJB.
                           <br/>
  -                        We will be able to do a query like
  -                        <em>give me all animals</em>. Thus
  -                        the uid's of
  -                        <code>Dog</code> and
  -                        <code>Cat</code>  objects must be unique across the
  +                        Now it is possible to do a query like
  +                        <em>give me all animals</em>. To make this working in OJB
  +                        the ID's of <code>Dog</code> and <code>Cat</code> objects must be unique across the
                           tables of both classes or else you may not get a vaild query result.
                           <br/>
                           The reason for this behaviour is the
  -                        <code>org.apache.ojb.broker.Identity</code>
  -                        class implementation (this may change in further versions).
  +                        <link href="ext:identity"><code>org.apache.ojb.broker.Identity</code></link>
  +                        class implementation (more details see javadoc/source of this class).
                       </p>
                   </section>
   
  @@ -778,11 +855,13 @@
                           try to build sequence names automatic.
                           </p>
   <source><![CDATA[
  -<sequence-manager className="XYZ">
  -...
  -    <attribute attribute-name="autoNaming" attribute-value="true"/>
  -...
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerNextValImpl">
  +    <attribute attribute-name="autoNaming" attribute-value="false"/>
   </sequence-manager>]]></source>
  +                    <p>
  +                        Keep in mind that user defined sequence names have to be
  +                        <link href="#extent-aware">extent-aware</link>.
  +                    </p>
                   </section>
   
                   <anchor id="sequenceManagerHandling"/>
  @@ -791,7 +870,7 @@
                       <p>
                           If you use multiple databases you have to declare a sequence manager in each
                           <code>jdbc-connection-descriptor</code>. If you don't specify a sequence manager
  -                        OJB use the default one (currently
  +                        OJB use a default one (currently
                           <code>ojb.broker.util.sequence.SequenceManagerHighLowImpl</code>).
                       </p>
                   </section>
  @@ -826,6 +905,9 @@
                           <code>field-descriptor</code>,
                           there is no reason to obtain UID directly from the sequence manager or to handle
                           UID in your object model.
  +                        <br/>
  +                        Except when using <em>user-defined</em> sequence manager implementations, in this case
  +                        it could be needed.
                       </p>
                       <note>
                           Don't use SequenceManagerFactory#getSequenceManager(PersistenceBroker broker), this
  @@ -840,27 +922,34 @@
                       <title>Any known pitfalls?</title>
                       <ul>
                           <li>
  -                            When enable a sequence manager implementation based on
  -                            <em>sequence-name</em> attributes
  -                            and if the name was not set as an attribute in the
  -                            <code>field-descriptor</code>
  -                            (
  -                            <link href="#sequence-name">see</link>), an simple algorithm was used to build the
  -                            sequence name.
  +                            When using <em>sequences</em> based sequence manager implementations it's possible
  +                            to enable auto-generation of <em>sequence names</em> - see
  +                            <link href="#auto-naming">autoNaming section</link>.
  +                            To build the <em>sequence name</em> an simple algorithm was used.
  +                            <br/>
                               <br/>
  -                            The algorithm try to get the top-level class of the field's enclosing class,
  +                            The algorithm try to get the <em>top-level class</em> of the field's
  +                            (the autoincrement <em>field-descriptor</em>) enclosing class,
                               if no top-level class was found, the table name of the field's enclosing class was used.
  -                            If a top-level class was found, the first found extent class table name was used as sequence name.
  +                            If a top-level class was found, the first found
  +                            <link href="site:repository/class-descriptor"><em>extent class</em></link> table name
  +                            was used as sequence name. The algorithm can be found in
  +                            <code>org.apache.ojb.broker.util.sequence.SequenceManagerHelper#buildSequenceName</code>.
  +                            <br/>
  +                            <br/>
  +                            When using base classes/interfaces with <em>extent classes</em> (declared in the
  +                            <link href="site:repository/class-descriptor"><em>class-descriptor</em></link>) based on
  +                            different database tables and the
  +                            <em>extent-class</em> entries in repository often change (e.g. add new top-level class,
  +                            change top-level class), the algorithm could be corrupted after restart of OJB, because
  +                            the first found extent class's table name could be change, hence the used sequence-name.
  +                            Now the ID generation start over and could clash with existing ID's.
                               <br/>
  -                            When using base classes/interfaces with extent classes based on different database tables
  -                            and the
  -                            <code>extent-class</code> entries in repository often change, the algorithm could be
  -                            corrupted, because the first found extent class's table name could be change.
                               <br/>
  -                            To avoid this, remove the implementation internal sequence name entry (e.g. OJB_HL_SEQ table
  -                            entry when using the Hi/Lo implementation, or remove the database sequence entry when using
  -                            the 'Nextval' implementation) in that case, or use custom sequence name attributes in the
  -                            field descriptor.
  +                            To avoid this, remove the implementation specific internal sequence name entry (e.g. from
  +                            table OJB_HL_SEQ when using the Hi/Lo implementation, or remove the database sequence
  +                            entry when using the 'Nextval' implementation) or use custom sequence name
  +                            attributes in the field descriptor.
                           </li>
                       </ul>
                   </section>
  
  
  
  No                   revision
  No                   revision
  1.3.2.8   +3 -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.7
  retrieving revision 1.3.2.8
  diff -u -r1.3.2.7 -r1.3.2.8
  --- site.xml	19 Feb 2005 21:49:53 -0000	1.3.2.7
  +++ site.xml	9 Mar 2005 15:23:05 -0000	1.3.2.8
  @@ -99,6 +99,7 @@
                   <field-conversion href="#field-conversion"/>
               </jdbc-types>
               <repository label="Repository File" href="repository.html" description="">
  +                <introduction href="#introduction"/>
                   <descriptor-repository href="#descriptor-repository"/>
                   <jdbc-connection-descriptor href="#jdbc-connection-descriptor"/>
                   <connection-pool href="#connection-pool"/>
  @@ -196,6 +197,7 @@
           <api href="api/">
               <javadoc href="index.html"/>
               <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"/>
               <class-descriptor href="org/apache/ojb/broker/metadata/ClassDescriptor.html"/>
               <descriptor-repository href="org/apache/ojb/broker/metadata/DescriptorRepository.html"/>
  
  
  

---------------------------------------------------------------------
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