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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
