You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by ar...@apache.org on 2005/11/10 02:25:36 UTC
cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides sequencemanager.xml
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