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/03/09 16:23:05 UTC
cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs site.xml
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