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/docu/guides sequencemanager.xml
Date Thu, 10 Nov 2005 01:25:36 GMT
arminw      2005/11/09 17:25:36

  Modified:    src/doc/forrest/src/documentation/content/xdocs/docu/guides
                        Tag: OJB_1_0_RELEASE sequencemanager.xml
  Log:
  update SequenceManagerStoredProcedureImpl section
  change section order
  
  Revision  Changes    Path
  No                   revision
  No                   revision
  1.1.2.7   +260 -191  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.6
  retrieving revision 1.1.2.7
  diff -u -r1.1.2.6 -r1.1.2.7
  --- sequencemanager.xml	12 Oct 2005 00:12:40 -0000	1.1.2.6
  +++ sequencemanager.xml	10 Nov 2005 01:25:36 -0000	1.1.2.7
  @@ -577,12 +577,83 @@
                   </section>
   
   
  +                <anchor id="native"/>
                   <section>
  -                    <title>Oracle-style sequencing</title>
  +                    <title>Database Identity-column based sequence manager</title>
  +                    <p>
  +                        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
  +                        <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.
  +                        <br/>
  +                        When using Identity columns it is not possible to retrieve the
next
  +                        valid UID before the object was written to database. As recently
as
  +                        the real object was written to database, you can ask the DB for
the last
  +                        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 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>
  -                        (By Ryan Vanderwerf et al.) This solution will give those seeking
an oracle-style sequence generator
  -                        a final answer (Identity columns really suck). If you are using
multiple
  -                        application servers in your environment, and your database does
not
  +                        To enable this sequence manager implementation set in your
  +                        <code>jdbc-connection-descriptor</code>:
  +                    </p>
  +                    <source><![CDATA[
  +<sequence-manager
  +    className="org.apache.ojb.broker.util.sequence.SequenceManagerNativeImpl">
  +</sequence-manager>
  +                        ]]></source>
  +                    <p>
  +                        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
  +                        <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
  +        name="identifier"
  +        column="NATIVE_ID"
  +        jdbc-type="BIGINT"
  +        primarykey="true"
  +        autoincrement="true"
  +        access="readonly"/>
  +                        ]]></source>
  +                    <p>
  +                        Limitations:
  +                        <br/>- The Identity columns have to
  +                        <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).
  +                        More info
  +                        <link href="#extent-aware">here</link>.
  +                    </p>
  +                </section>
  +
  +
  +                <section>
  +                    <title>Stored Procedures based (Oracle-style) sequencing</title>
  +                    <p>
  +                        <em>(By Ryan Vanderwerf et al.)</em>
  +                        <br/>
  +                        This solution will give those seeking an oracle-style
  +                        sequence generator a final answer (Identity columns really suck).
If you are using
  +                        multiple application servers in your environment, and your database
does not
                           support read locking like Microsoft SQL Server, this is the only
                           safe way to guarantee unique keys (HighLowSequenceManager WILL
                           give out duplicate keys, and corrupt your data).
  @@ -591,34 +662,78 @@
                           <code>SequenceManagerStoredProcedureImpl</code> implementation
enabled database
                           sequence key generation in a
                           <em>Oracle-style</em> for all databases (e.g. MSSQL,
MySQL, DB2, ...).
  -                        <br/>
  -                        First add a new table
  -                        <code>OJB_NEXTVAL_SEQ</code> to
  -                        your database.
  +                    </p>
  +                    <p>
  +                        To declare this <em>sequence manager</em> implementation
specify a
  +                        <code>sequence-manager</code> element within the
  +                        <link href="site:repository/jdbc-connection-descriptor">jdbc-connection-descriptor</link>:
                       </p>
                       <source><![CDATA[
  +<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerStoredProcedureImpl">
  +    <attribute attribute-name="seq.start" attribute-value="200000"/>
  +    <attribute attribute-name="autoNaming" attribute-value="true"/>
  +</sequence-manager>]]></source>
  +                    <p>
  +                        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
when
  +                        <link href="#auto-naming">autoNaming</link> is enabled.
  +                    </p>
  +                    <ul>
  +                        <li>
  +                            Add a new table <code>OJB_NEXTVAL_SEQ</code> to
your database.
  +                        </li>
  +                        <li>
  +                            You will also need a stored procedure called
  +                            <code>ojb_nextval_proc</code> that will take care
of giving you a
  +                            guaranteed unique sequence number.
  +                        </li>
  +                    </ul>
  +                    <p>
  +                        Below you can find the stored procedures you need to
  +                        use sequencing for MSSQL server and Informix.
  +                        <br/>
  +                        You have to adapt the scripts for other databases (We are interested
  +                        in scripts for other databases).
  +                    </p>
  +                    <p>
  +                        Here you can find the currently supported databases and the statements
to
  +                        create the sql functions:
  +                    </p>
  +                    <table>
  +                        <tr>
  +                            <th>Database</th>
  +                            <th>Table Statement</th>
  +                            <th>Stored Procedure</th>
  +                        </tr>
  +                        <tr>
  +                            <td>MSSQL</td>
  +                            <td>
  +                                <source><![CDATA[
  +DROP TABLE OJB_NEXTVAL_SEQ;
   CREATE TABLE OJB_NEXTVAL_SEQ
   (
       SEQ_NAME    VARCHAR(150) NOT NULL,
       MAX_KEY     INTEGER,
  -    CONSTRAINT SYS_PK_OJB_NEXTVAL PRIMARY KEY(SEQ_NAME)
  -)]]></source>
  -                    <p>
  -                        You will also need a stored procedure called
  -                        <code>ojb_nextval_proc</code>
  -                        that will take care of giving you a guaranteed unique
  -                        sequence number.
  -                        <br/>
  -                        Here is an example for the stored procedure you need to
  -                        use sequencing for MSSQL server:
  -                    </p>
  -                    <source><![CDATA[
  +    CONSTRAINT SYS_PK_OJB_NEXTVAL
  +    PRIMARY KEY(SEQ_NAME)
  +);]]></source>
  +                            </td>
  +                            <td>
  +                                <source><![CDATA[
   CREATE PROCEDURE OJB_NEXTVAL_PROC
   @SEQ_NAME varchar(150)
   AS
   declare @MAX_KEY BIGINT
  --- return an error if sequence does not exist
  --- so we will know if someone truncates the table
  +-- return an error if
  +-- sequence does not exist
  +-- so we will know if someone
  +-- truncates the table
   set @MAX_KEY = 0
   
   UPDATE OJB_NEXTVAL_SEQ
  @@ -629,27 +744,50 @@
   select 1/0
   else
   select @MAX_KEY
  -RETURN @MAX_KEY ]]></source>
  -                    <p>
  -                        You have to adapt this script if MSSQL was not used
  -                        (We are interested in scripts for other databases).
  -                        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>]]></source>
  -                    <p>
  -                        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
when
  -                        <link href="#auto-naming">autoNaming</link> is enabled.
  -                    </p>
  +RETURN @MAX_KEY
  +                                ]]></source>
  +                            </td>
  +                        </tr>
  +                        <tr>
  +                            <td>Informix</td>
  +                            <td>
  +                                <source><![CDATA[
  +drop table ojb_nextval_seq;
  +create table ojb_nextval_seq
  +(
  +    seq_name    varchar(250,0) not null,
  +    max_key     int8,
  +    primary key(seq_name)
  +);]]></source>
  +                            </td>
  +                            <td>
  +                                <source><![CDATA[
  +create function ojb_nextval_proc
  +(out arg1 int8, arg2 varchar(250,250))
  +returns int8;
  +let arg1 = 0;
  +update ojb_nextval_seq
  +set max_key = max_key + 1
  +where seq_name = arg2;
  +select max_key into arg1
  +from ojb_nextval_seq
  +where seq_name = arg2;
  +return arg1;
  +end function;]]></source>
  +                            </td>
  +                        </tr>
  +                        <tr>
  +                            <td>Oracle</td>
  +                            <td>
  +                                <source><![CDATA[
  +TODO]]></source>
  +                            </td>
  +                            <td>
  +                                <source><![CDATA[
  +TODO]]></source>
  +                            </td>
  +                        </tr>
  +                    </table>
                       <p>
                           Limitations:
                           <br/>- currently none known
  @@ -711,164 +849,95 @@
                       </p>
                   </section>
   
  -
  -                <anchor id="native"/>
  -                <section>
  -                    <title>Identity based sequence manager</title>
  -                    <p>
  -                        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
  -                        <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.
  -                        <br/>
  -                        When using Identity columns it is not possible to retrieve the
next
  -                        valid UID before the object was written to database. As recently
as
  -                        the real object was written to database, you can ask the DB for
the last
  -                        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 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
  -                        <code>jdbc-connection-descriptor</code>:
  -                    </p>
  -                    <source><![CDATA[
  -<sequence-manager
  -    className="org.apache.ojb.broker.util.sequence.SequenceManagerNativeImpl">
  -</sequence-manager>
  -                        ]]></source>
  -                    <p>
  -                        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
  -                        <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
  -        name="identifier"
  -        column="NATIVE_ID"
  -        jdbc-type="BIGINT"
  -        primarykey="true"
  -        autoincrement="true"
  -        access="readonly"/>
  -                        ]]></source>
  -                    <p>
  -                        Limitations:
  -                        <br/>- The Identity columns have to
  -                        <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).
  -                        More info
  -                        <link href="#extent-aware">here</link>.
  -                    </p>
  -                </section>
  +            </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[
  +            <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"
  +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"
  -    />
  +<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>
  +                <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>
  +            </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[
  +            <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"/>
  +<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>
  -
  +                <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>
   
   
  
  
  

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