Skip to main content
Jump to: navigation, search

Difference between revisions of "Introduction to Relational Projects (ELUG)"

m (Sequencing and Preallocation Size)
m
Line 1: Line 1:
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Introduction to Relational Projects (ELUG)|Related Topics]]</div>
+
[[Special:Whatlinkshere/Introduction to Relational Projects (ELUG)|Related Topics]]</div> This section provides an overview of relational projects and focuses on building these projects for relational and object-relational data type databases.
 
+
This section provides an overview of relational projects and focuses on building these projects for relational and object-relational data type databases.
+
  
 
For information on project concepts and features common to more than one type of EclipseLink projects, see [[Introduction%20to%20Projects (ELUG)|Introduction to Projects]].
 
For information on project concepts and features common to more than one type of EclipseLink projects, see [[Introduction%20to%20Projects (ELUG)|Introduction to Projects]].
Line 9: Line 7:
  
 
==Building Relational Projects==
 
==Building Relational Projects==
 
 
Use a relational project for transactional persistence of Java objects to a conventional ''relational'' database or to an ''object-relational data type'' database that supports data types specialized for object storage, both accessed using JDBC.
 
Use a relational project for transactional persistence of Java objects to a conventional ''relational'' database or to an ''object-relational data type'' database that supports data types specialized for object storage, both accessed using JDBC.
  
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
| align="left" |
 
| align="left" |
'''Note:''' If you are using Workbench, you must add your JDBC driver to the Workbench classpath. For more information, see [[Using%20Workbench%20(ELUG)|Configuring the Workbench Environment]].
+
'''Note:''' If you are using Workbench, you must add your JDBC driver to the Workbench classpath. For more information, see [[Using%20Workbench%20(ELUG)#Configuring the Workbench Environment|Configuring the Workbench Environment]].
 
|}
 
|}
  
Line 24: Line 21:
  
 
===How to Build Relational Projects for a Relational Database===
 
===How to Build Relational Projects for a Relational Database===
 
 
The Workbench provides complete support for creating relational projects that map Java objects to a conventional relational database accessed using JDBC.
 
The Workbench provides complete support for creating relational projects that map Java objects to a conventional relational database accessed using JDBC.
  
Line 41: Line 37:
 
Data Source
 
Data Source
 
| headers="r2c1-t3 r1c2-t3" align="left" |
 
| headers="r2c1-t3 r1c2-t3" align="left" |
For more information, see the following:
+
[[Introduction%20to%20Data%20Access%20(ELUG)|DatabaseLogin]] or [[Introduction%20to%20Data%20Access%20(ELUG)|Database Platforms]]
* [[Introduction%20to%20Data%20Access%20(ELUG)|DatabaseLogin]]
+
* [[Introduction%20to%20Data%20Access%20(ELUG)|Database Platforms]]
+
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
 
Descriptors
 
Descriptors
 
| headers="r3c1-t3 r1c2-t3" align="left" |
 
| headers="r3c1-t3 r1c2-t3" align="left" |
For more information, see [[Introduction%20to%20Relational%20Descriptors%20(ELUG)|Relational Descriptors]].
+
[[Introduction%20to%20Relational%20Descriptors%20(ELUG)|Relational Descriptors]]
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
 
Mappings
 
Mappings
 
| headers="r4c1-t3 r1c2-t3" align="left" |
 
| headers="r4c1-t3 r1c2-t3" align="left" |
For more information, see the following:
+
[[Relational Mappings (ELUG)]]
* [[Relational Mappings (ELUG)]]
+
 
|}
 
|}
  
  
  
For more information, see [[Creating%20a%20Relational%20Project%20(ELUG)|Creating a Relational Project]].
+
For more information, see [[Creating%20a%20Relational%20Project%20(ELUG)#Creating a Relational Project|Creating a Relational Project]].
  
  
  
 
===How to Build Relational Projects for an Object-Relational Data Type Database===
 
===How to Build Relational Projects for an Object-Relational Data Type Database===
 
 
The Workbench does not currently support relational projects for an object-relational data type database. You must create such a relational project in Java.
 
The Workbench does not currently support relational projects for an object-relational data type database. You must create such a relational project in Java.
  
Line 70: Line 62:
  
 
When using EclipseLink to build a relational project for an object-relational data type database, consider the following:
 
When using EclipseLink to build a relational project for an object-relational data type database, consider the following:
 
 
* You must create a Java class and a EclipseLink <tt>ObjectRelationalDescriptor</tt> for each structured type (<tt>Struct/object-type</tt>).
 
* You must create a Java class and a EclipseLink <tt>ObjectRelationalDescriptor</tt> for each structured type (<tt>Struct/object-type</tt>).
 
* EclipseLink supports only arrays (<tt>Varrays</tt>) of basic types or arrays on structured types (<tt>Struct/object-type</tt>).EclipseLink does not support arrays of <tt>Refs</tt> or arrays of nested tables.
 
* EclipseLink supports only arrays (<tt>Varrays</tt>) of basic types or arrays on structured types (<tt>Struct/object-type</tt>).EclipseLink does not support arrays of <tt>Refs</tt> or arrays of nested tables.
Line 76: Line 67:
  
 
The general development process for building a relational project for an object-relational data type database is as follows:
 
The general development process for building a relational project for an object-relational data type database is as follows:
 
 
# Define structured object-types in the database.
 
# Define structured object-types in the database.
 
# Define tables of the structured object-types in the database.
 
# Define tables of the structured object-types in the database.
Line 82: Line 72:
 
# Create a relational project (see [[Creating%20a%20Project%20(ELUG)|Creating a Project]]).
 
# Create a relational project (see [[Creating%20a%20Project%20(ELUG)|Creating a Project]]).
 
# Create an object-relational data type descriptor for each Java class (see [[Creating%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)|Creating an Object-Relational Data Type Descriptor]]).
 
# Create an object-relational data type descriptor for each Java class (see [[Creating%20an%20Object-Relational%20Data%20Type%20Descriptor%20(ELUG)|Creating an Object-Relational Data Type Descriptor]]).
# Create object-relational data type mappings from each persistent field of each Java class to the corresponding object-types and object-type tables.For more information, see the following:
+
# Create object-relational data type mappings from each persistent field of each Java class to the corresponding object-types and object-type tables.<br>For more information, see the following:
 
#* [[Creating%20a%20Mapping%20(ELUG)|Creating a Mapping]]
 
#* [[Creating%20a%20Mapping%20(ELUG)|Creating a Mapping]]
 
#* [[Configuring%20an%20Object-Relational%20Data%20Type%20Mapping (ELUG)|Configuring an Object-Relational Data Type Mapping]]
 
#* [[Configuring%20an%20Object-Relational%20Data%20Type%20Mapping (ELUG)|Configuring an Object-Relational Data Type Mapping]]
Line 98: Line 88:
 
Data Source
 
Data Source
 
| headers="r2c1-t4 r1c2-t4" align="left" |
 
| headers="r2c1-t4 r1c2-t4" align="left" |
For more information, see the following:
+
[[Introduction%20to%20Data%20Access%20(ELUG)#DatabaseLogin|DatabaseLogin]] or [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|Database Platforms]]
* [[Introduction%20to%20Data%20Access%20(ELUG)#DatabaseLogin|DatabaseLogin]]
+
* [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|Database Platforms]]
+
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t4" headers="r1c1-t4" align="left" |
 
| id="r3c1-t4" headers="r1c1-t4" align="left" |
 
Descriptors
 
Descriptors
 
| headers="r3c1-t4 r1c2-t4" align="left" |
 
| headers="r3c1-t4 r1c2-t4" align="left" |
For more information, see [[Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)|Object-Relational Data Type Descriptors]].
+
[[Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)|Object-Relational Data Type Descriptors]]
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t4" headers="r1c1-t4" align="left" |
 
| id="r4c1-t4" headers="r1c1-t4" align="left" |
 
Mappings
 
Mappings
 
| headers="r4c1-t4 r1c2-t4" align="left" |
 
| headers="r4c1-t4 r1c2-t4" align="left" |
For more information, see the following:
+
[[Object-Relational Data Type Mappings (ELUG)]]
*[[Object-Relational Data Type Mappings (ELUG)]]
+
 
|}
 
|}
  
  
  
For more information, see [[Creating%20a%20Relational%20Project%20(ELUG)|Creating a Relational Project]].
+
For more information, see [[Creating%20a%20Relational%20Project%20(ELUG)#Creating a Relational Project|Creating a Relational Project]].
 +
 
 +
 
  
 
==Sequencing in Relational Projects==
 
==Sequencing in Relational Projects==
 
+
In an relational project, you store persistent objects for your application in database tables that represent the class of instantiated object. As the [[#Figure 23-1|Sequencing Elements in a Class Database Table]] figure shows, each row of the VEHICLE_POOL table represents an instantiated object from that class, and the VEH_ID column holds the primary key for each object.
In an relational project, you store persistent objects for your application in database tables that represent the class of instantiated object. As [[#Figure 23-1|Sequencing Elements in a Class Database Table]] shows, each row of the VEHICLE_POOL table represents an instantiated object from that class, and the VEH_ID column holds the primary key for each object.
+
  
  
Line 128: Line 116:
 
[[Image:seqtable.gif|Sequencing Elements in a Class Database Table]]
 
[[Image:seqtable.gif|Sequencing Elements in a Class Database Table]]
  
You configure EclipseLink sequencing at the project or session level (see [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Sequencing at the Project Level]] or [[Configuring%20a%20Database%20Login%20(ELUG)|Configuring Sequencing at the Session Level]]) to tell EclipseLink how to obtain values for the primary key column: that is, what type of sequencing to use (see [[#Sequencing Types]]).
+
You configure EclipseLink sequencing at the project or session level (see [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Sequencing at the Project Level|Configuring Sequencing at the Project Level]] or [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Sequencing at the Session Level|Configuring Sequencing at the Session Level]]) to tell EclipseLink how to obtain values for the primary key column: that is, what type of sequencing to use (see [[#Sequencing Types|Sequencing Types]]).
  
You configure EclipseLink sequencing at the descriptor level (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)|Configuring Sequencing at the Descriptor Level]]) to tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created.
+
You configure EclipseLink sequencing at the descriptor level (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Sequencing at the Descriptor Level|Configuring Sequencing at the Descriptor Level]]) to tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created.
  
  
Line 142: Line 130:
  
 
This section describes the following:
 
This section describes the following:
 
+
* [[#Sequencing Configuration Options|Sequencing Configuration Options]]
* [[#Sequencing Configuration Options]]
+
* [[#Sequencing Types|Sequencing Types]]
* [[#Sequencing Types]]
+
* [[#Sequencing and Preallocation Size|Sequencing and Preallocation Size]]
* [[#Sequencing and Preallocation Size]]
+
  
  
  
 
===Sequencing Configuration Options===
 
===Sequencing Configuration Options===
 
 
You can configure sequencing using either the Workbench or Java (but not both).
 
You can configure sequencing using either the Workbench or Java (but not both).
  
Using the Workbench, create one sequence with a single preallocation size that applies to all descriptors that require sequencing. You can configure table sequencing (see [[#Table Sequencing]]) or native sequencing (see [[#Native Sequencing with an Oracle Database Platform]]). If you choose table sequencing, you can either use default table and column names or specify your own (see [[#Default Versus Custom Sequence Table]]).
+
Using the Workbench, create one sequence with a single preallocation size that applies to all descriptors that require sequencing. You can configure table sequencing (see [[#Table Sequencing|Table Sequencing]]) or native sequencing (see [[#Native Sequencing with an Oracle Database Platform|Native Sequencing with an Oracle Database Platform]]). If you choose table sequencing, you can either use default table and column names or specify your own (see [[#Default Versus Custom Sequence Table|Default Versus Custom Sequence Table]]).
  
Using Java, you can configure any sequence type that EclipseLink supports (see [[#Sequencing Types]]). You can create any number and combination of sequences per project. You can create a sequence object explicitly or use the platform default sequence (see [[#Default Sequencing]]). You can associate the same sequence with more than one descriptor or associate different sequences (and different sequence types) to various descriptors. You can configure a separate preallocation size for each descriptor's sequence. For more information, see [[Configuring%20a%20Database%20Login%20(ELUG)|How to Configure Sequencing at the Session Level Using Java]].
+
Using Java, you can configure any sequence type that EclipseLink supports (see [[#Sequencing Types|Sequencing Types]]). You can create any number and combination of sequences per project. You can create a sequence object explicitly or use the platform default sequence (see [[#Default Sequencing|Default Sequencing]]). You can associate the same sequence with more than one descriptor or associate different sequences (and different sequence types) to various descriptors. You can configure a separate preallocation size for each descriptor's sequence. For more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#How to Configure Sequencing at the Session Level Using Java|How to Configure Sequencing at the Session Level Using Java]].
  
  
  
 
===Sequencing Types===
 
===Sequencing Types===
 
 
EclipseLink supports the following sequence types:
 
EclipseLink supports the following sequence types:
 
+
* [[#Table Sequencing|Table Sequencing]]
* [[#Table Sequencing]]
+
* [[#Unary Table Sequencing|Unary Table Sequencing]]
* [[#Unary Table Sequencing]]
+
* [[#Query Sequencing|Query Sequencing]]
* [[#Query Sequencing]]
+
* [[#Default Sequencing|Default Sequencing]]
* [[#Default Sequencing]]
+
* [[#Native Sequencing with an Oracle Database Platform|Native Sequencing with an Oracle Database Platform]]
* [[#Native Sequencing with an Oracle Database Platform]]
+
* [[#Native Sequencing with a Non-Oracle Database Platform|Native Sequencing with a Non-Oracle Database Platform]]
* [[#Native Sequencing with a Non-Oracle Database Platform]]
+
  
  
  
 
====Table Sequencing====
 
====Table Sequencing====
 
 
With table sequencing, you create a single database table that includes sequencing information for one or more sequenced objects in the project. EclipseLink maintains this table to track sequence numbers for these object types.
 
With table sequencing, you create a single database table that includes sequencing information for one or more sequenced objects in the project. EclipseLink maintains this table to track sequence numbers for these object types.
  
As [[#Figure 23-2|EclipseLink Table Sequence Table]] shows, the table may contain sequencing information for more than one class that uses sequencing. The default table is called <tt>SEQUENCE</tt> and contains two columns:
+
As the [[#Figure 23-2|EclipseLink Table Sequence Table]] figure shows, the table may contain sequencing information for more than one class that uses sequencing. The default table is called <tt>SEQUENCE</tt> and contains two columns:
 
+
 
* <tt>SEQ_NAME</tt>, which specifies the class type to which the selected row refers
 
* <tt>SEQ_NAME</tt>, which specifies the class type to which the selected row refers
 
* <tt>SEQ_COUNT</tt>, which specifies the highest sequence number currently allocated for the object represented in the selected row
 
* <tt>SEQ_COUNT</tt>, which specifies the highest sequence number currently allocated for the object represented in the selected row
Line 192: Line 174:
  
 
You can create the <tt>SEQUENCE</tt> table on the database in one of two ways:
 
You can create the <tt>SEQUENCE</tt> table on the database in one of two ways:
 
 
* Use the Workbench to create the table. See [[Using%20Workbench%20(ELUG)#Generating Tables on the Database|Generating Tables on the Database]] for more information.
 
* Use the Workbench to create the table. See [[Using%20Workbench%20(ELUG)#Generating Tables on the Database|Generating Tables on the Database]] for more information.
 
* Use the EclipseLink table creator to create and update the table manually. See [[Using%20Workbench%20(ELUG)#Generating SQL Creation Scripts|Generating SQL Creation Scripts]] for more information.
 
* Use the EclipseLink table creator to create and update the table manually. See [[Using%20Workbench%20(ELUG)#Generating SQL Creation Scripts|Generating SQL Creation Scripts]] for more information.
Line 201: Line 182:
  
 
=====Default Versus Custom Sequence Table=====
 
=====Default Versus Custom Sequence Table=====
 
 
In most cases, you implement table sequencing using the default table and column names. However, you may want to specify your own table and column names if the following holds true:
 
In most cases, you implement table sequencing using the default table and column names. However, you may want to specify your own table and column names if the following holds true:
 
 
* You want to use an existing sequence table for sequencing.
 
* You want to use an existing sequence table for sequencing.
 
* You do not want to use the default naming convention for the table and its columns.
 
* You do not want to use the default naming convention for the table and its columns.
  
====Unary Table Sequencing====
 
  
 +
 +
====Unary Table Sequencing====
 
Although similar to table sequencing (see [[#Table Sequencing|Table Sequencing]]), with unary table sequencing, you create a separate sequence table for each sequenced object in the project.
 
Although similar to table sequencing (see [[#Table Sequencing|Table Sequencing]]), with unary table sequencing, you create a separate sequence table for each sequenced object in the project.
  
Line 219: Line 199:
 
[[Image:seqtblun.gif|EclipseLink Unary Table Sequence Table]]
 
[[Image:seqtblun.gif|EclipseLink Unary Table Sequence Table]]
  
When you configure sequencing at the descriptor level, you specify the sequence name for the class: this is the name of the unary table sequence table. [[#Figure 23-3|EclipseLink Unary Table Sequence Table']] shows a unary table sequence for the <tt>Employee</tt> class. The <tt>Employee</tt> class descriptor is configured (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Sequencing at the Descriptor Level|Configuring Sequencing at the Descriptor Level]]) with a sequence name of <tt>EMP_SEQ</tt> to match the unary table sequence table name. EclipseLink adds a row to this table and initializes the <tt>SEQUENCE</tt> column to the value <tt>1</tt>.
+
When you configure sequencing at the descriptor level, you specify the sequence name for the class: this is the name of the unary table sequence table. The [[#Figure 23-3|EclipseLink Unary Table Sequence Table]] figure shows a unary table sequence for the <tt>Employee</tt> class. The <tt>Employee</tt> class descriptor is configured (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Sequencing at the Descriptor Level|Configuring Sequencing at the Descriptor Level]]) with a sequence name of <tt>EMP_SEQ</tt> to match the unary table sequence table name. EclipseLink adds a row to this table and initializes the <tt>SEQUENCE</tt> column to the value <tt>1</tt>.
  
 
Each time a new class is created, EclipseLink obtains the required sequence value from the single row of the unary sequence table corresponding to the class. For efficiency, EclipseLink uses preallocation to reduce the number of table accesses required to obtain sequence values (see [[#Sequencing and Preallocation Size|Sequencing and Preallocation Size]]).
 
Each time a new class is created, EclipseLink obtains the required sequence value from the single row of the unary sequence table corresponding to the class. For efficiency, EclipseLink uses preallocation to reduce the number of table accesses required to obtain sequence values (see [[#Sequencing and Preallocation Size|Sequencing and Preallocation Size]]).
  
 
You can create the unary table sequence table on the database in one of two ways:
 
You can create the unary table sequence table on the database in one of two ways:
 
 
* Use the Workbench to create the table. See [[Using%20Workbench%20(ELUG)#Generating Tables on the Database|Generating Tables on the Database]] for more information.
 
* Use the Workbench to create the table. See [[Using%20Workbench%20(ELUG)#Generating Tables on the Database|Generating Tables on the Database]] for more information.
 
* Use the EclipseLink table creator to create and update the table manually. See [[Using%20Workbench%20(ELUG)#Generating SQL Creation Scripts|Generating SQL Creation Scripts]] for more information.
 
* Use the EclipseLink table creator to create and update the table manually. See [[Using%20Workbench%20(ELUG)#Generating SQL Creation Scripts|Generating SQL Creation Scripts]] for more information.
  
 
Currently, you can only configure unary table sequencing in Java using the <tt>UnaryTableSequence</tt> class (for more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#How to Configure Sequencing at the Session Level Using Java)|How to Configure Sequencing at the Session Level Using Java]]).
 
Currently, you can only configure unary table sequencing in Java using the <tt>UnaryTableSequence</tt> class (for more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#How to Configure Sequencing at the Session Level Using Java)|How to Configure Sequencing at the Session Level Using Java]]).
 +
  
 
====Query Sequencing====
 
====Query Sequencing====
 
 
With query sequencing, you can access a sequence resource using custom read (<tt>ValueReadQuery</tt>) and update (<tt>DataModifyQuery</tt>) queries and a preallocation size that you specify. This allows you to perform sequencing using stored procedures and allows you to access sequence resources that are not supported by the other sequencing types that EclipseLink provides.
 
With query sequencing, you can access a sequence resource using custom read (<tt>ValueReadQuery</tt>) and update (<tt>DataModifyQuery</tt>) queries and a preallocation size that you specify. This allows you to perform sequencing using stored procedures and allows you to access sequence resources that are not supported by the other sequencing types that EclipseLink provides.
  
Currently, you can only configure query sequencing in Java using the <tt>QuerySequence</tt> class (for more information, see [[Configuring%20a%20Database%20Login%20(ELUG)|Configuring Query Sequencing]]).
+
Currently, you can only configure query sequencing in Java using the <tt>QuerySequence</tt> class (for more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Query Sequencing|Configuring Query Sequencing]]).
  
  
  
 
====Default Sequencing====
 
====Default Sequencing====
 
+
The platform owned by a login is responsible for providing a default sequence instance appropriate for the platform type. For example, by default, a <tt>DatabasePlatform</tt> provides a table sequence using the default table and column names (see [[#Table Sequencing|Table Sequencing]]).
The platform owned by a login is responsible for providing a default sequence instance appropriate for the platform type. For example, by default, a <tt>DatabasePlatform</tt> provides a table sequence using the default table and column names (see [[#Table Sequencing]]).
+
  
 
You can access this default sequence directly using <tt>DatasourceLogin</tt> method <tt>getDefaultSequence</tt>, or indirectly by using the <tt>DefaultSequence</tt> class, a wrapper for the platform default sequence.
 
You can access this default sequence directly using <tt>DatasourceLogin</tt> method <tt>getDefaultSequence</tt>, or indirectly by using the <tt>DefaultSequence</tt> class, a wrapper for the platform default sequence.
  
If you associate a descriptor with a nonexistent sequence, the EclipseLink runtime will create an instance of <tt>DefaultSequence</tt> to provide sequencing for that descriptor. For more information, see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)|Configuring the Platform Default Sequence]].
+
If you associate a descriptor with a nonexistent sequence, the EclipseLink runtime will create an instance of <tt>DefaultSequence</tt> to provide sequencing for that descriptor. For more information, see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring the Platform Default Sequence|Configuring the Platform Default Sequence]].
  
 
The main purpose of the <tt>DefaultSequence</tt> is to allow a sequence to use a different pre-allocation size than the project default.
 
The main purpose of the <tt>DefaultSequence</tt> is to allow a sequence to use a different pre-allocation size than the project default.
  
Currently, you can only make use of default sequencing in Java (for more information, see [[Configuring%20a%20Database%20Login%20(ELUG)|Using the Platform Default Sequence]]).
+
Currently, you can only make use of default sequencing in Java (for more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#Using the Platform Default Sequence|Using the Platform Default Sequence]]).
  
  
  
 
====Native Sequencing with an Oracle Database Platform====
 
====Native Sequencing with an Oracle Database Platform====
 +
EclipseLink support for native sequencing with Oracle Databases is similar to table sequencing (see [[#Table Sequencing|Table Sequencing]]), except that EclipseLink does not maintain a table in the database. Instead, the database contains a sequence object that stores the current maximum number and preallocation size for sequenced objects. The sequence name configured at the descriptor level identifies the sequence object responsible for providing sequencing values for the descriptor's reference class.
  
EclipseLink support for native sequencing with Oracle Databases is similar to table sequencing (see [[#Table Sequencing]]), except that EclipseLink does not maintain a table in the database. Instead, the database contains a sequence object that stores the current maximum number and preallocation size for sequenced objects. The sequence name configured at the descriptor level identifies the sequence object responsible for providing sequencing values for the descriptor's reference class.
+
You can configure native sequencing using Workbench or Java. For more information about configuring table sequencing, see [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Sequencing at the Project Level|Configuring Sequencing at the Project Level]] or [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Sequencing at the Session Level|Configuring Sequencing at the Session Level]].
 
+
You can configure native sequencing using Workbench or Java. For more information about configuring table sequencing, see [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Sequencing at the Project Level]] or [[Configuring%20a%20Database%20Login%20(ELUG)|Configuring Sequencing at the Session Level]].
+
  
  
  
 
=====Understanding the Oracle SEQUENCE Object=====
 
=====Understanding the Oracle SEQUENCE Object=====
 
 
The Oracle <tt>SEQUENCE</tt> object implements a strategy that closely resembles EclipseLink sequencing: it implements an <tt>INCREMENT</tt> construct that parallels the EclipseLink preallocation size, and a <tt>sequence.nextval</tt> construct that parallels the <tt>SEQ_COUNT</tt> field in the EclipseLink <tt>SEQUENCE</tt> table in table sequencing. This implementation enables EclipseLink to use the Oracle <tt>SEQUENCE</tt> object as if it were a EclipseLink <tt>SEQUENCE</tt> table, but eliminates the need for EclipseLink to create and maintain the table.
 
The Oracle <tt>SEQUENCE</tt> object implements a strategy that closely resembles EclipseLink sequencing: it implements an <tt>INCREMENT</tt> construct that parallels the EclipseLink preallocation size, and a <tt>sequence.nextval</tt> construct that parallels the <tt>SEQ_COUNT</tt> field in the EclipseLink <tt>SEQUENCE</tt> table in table sequencing. This implementation enables EclipseLink to use the Oracle <tt>SEQUENCE</tt> object as if it were a EclipseLink <tt>SEQUENCE</tt> table, but eliminates the need for EclipseLink to create and maintain the table.
  
Line 271: Line 247:
  
 
=====Using SEQUENCE Objects=====
 
=====Using SEQUENCE Objects=====
 
 
Your database administrator (DBA) must create a <tt>SEQUENCE</tt> object on the database for every sequencing series your application requires. If every class in your application requires its own sequence, the DBA creates a <tt>SEQUENCE</tt> object for every class; if you design several classes to share a sequence, the DBA need create only one <tt>SEQUENCE</tt> object for those classes.
 
Your database administrator (DBA) must create a <tt>SEQUENCE</tt> object on the database for every sequencing series your application requires. If every class in your application requires its own sequence, the DBA creates a <tt>SEQUENCE</tt> object for every class; if you design several classes to share a sequence, the DBA need create only one <tt>SEQUENCE</tt> object for those classes.
  
For example, in [[#Figure 23-4|Example of Database Tables–Racquet Information]], consider the case of a sporting goods manufacturer that manufactures three styles of tennis racquet. The data for these styles of racquet are stored in the database as follows:
+
For example, in the [[#Figure 23-4|Example of Database Tables–Racquet Information]] figure, consider the case of a sporting goods manufacturer that manufactures three styles of tennis racquet. The data for these styles of racquet are stored in the database as follows:
 
+
 
* Each style of racquet has its own class table.
 
* Each style of racquet has its own class table.
 
* Each manufactured racquet is an object represented by a line in the class table.
 
* Each manufactured racquet is an object represented by a line in the class table.
Line 287: Line 261:
  
 
The manufacturer can do either of the following:
 
The manufacturer can do either of the following:
 
 
* ''Use separate sequencing for each racquet style.'' The DBA builds three separate <tt>SEQUENCE</tt> objects, perhaps called <tt>ATTACK_SEQ</tt>, <tt>VOLLEY_SEQ</tt>, and <tt>PROX_SEQ</tt>. Each different racquet line has its own serial number series, and there may be duplication of serial numbers between the lines (for example: all three styles may include a racquet with serial number 1234).
 
* ''Use separate sequencing for each racquet style.'' The DBA builds three separate <tt>SEQUENCE</tt> objects, perhaps called <tt>ATTACK_SEQ</tt>, <tt>VOLLEY_SEQ</tt>, and <tt>PROX_SEQ</tt>. Each different racquet line has its own serial number series, and there may be duplication of serial numbers between the lines (for example: all three styles may include a racquet with serial number 1234).
 
* ''Use a single sequencing series for all racquets.'' The DBA builds a single <tt>SEQUENCE</tt> object (perhaps called <tt>RACQUET_SEQ</tt>). The manufacturer assigns serial numbers to racquets as they are produced, without regard for the style of racquet.
 
* ''Use a single sequencing series for all racquets.'' The DBA builds a single <tt>SEQUENCE</tt> object (perhaps called <tt>RACQUET_SEQ</tt>). The manufacturer assigns serial numbers to racquets as they are produced, without regard for the style of racquet.
 +
  
 
====Native Sequencing with a Non-Oracle Database Platform====
 
====Native Sequencing with a Non-Oracle Database Platform====
 
 
Several databases support a type of native sequencing in which the database management system generates the sequence numbers.
 
Several databases support a type of native sequencing in which the database management system generates the sequence numbers.
  
 
When you create a database table for a class that uses native sequencing, include a primary key column, and set the column type as follows:
 
When you create a database table for a class that uses native sequencing, include a primary key column, and set the column type as follows:
 
 
* For Sybase and Microsoft SQL Server databases, set the primary key field to the type <tt>IDENTITY</tt>.
 
* For Sybase and Microsoft SQL Server databases, set the primary key field to the type <tt>IDENTITY</tt>.
 
* For IBM Informix databases, set the primary key field to the type <tt>SERIAL</tt>.
 
* For IBM Informix databases, set the primary key field to the type <tt>SERIAL</tt>.
Line 304: Line 276:
  
 
At this point, and before the transaction closes, EclipseLink reads back the primary key for the new object so that the object has an identity in the EclipseLink cache.
 
At this point, and before the transaction closes, EclipseLink reads back the primary key for the new object so that the object has an identity in the EclipseLink cache.
 
  
  
Line 314: Line 285:
  
  
If your database provides native sequencing, but EclipseLink does not directly support it, you may be able to access the native sequence object using a query sequence and stored procedures. For more information, see [[#Query Sequencing]].
+
If your database provides native sequencing, but EclipseLink does not directly support it, you may be able to access the native sequence object using a query sequence and stored procedures. For more information, see [[#Query Sequencing|Query Sequencing]].
  
You can configure native sequencing using Workbench or Java. We recommend that you use JDeveloper. For more information about configuring table sequencing, see [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Sequencing at the Project Level]] or [[Configuring%20a%20Database%20Login%20(ELUG)|Configuring Sequencing at the Session Level]].
+
You can configure native sequencing using Workbench or Java. We recommend that you use the Workbench. For more information about configuring table sequencing, see [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Sequencing at the Project Level|Configuring Sequencing at the Project Level]] or [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Sequencing at the Session Level|Configuring Sequencing at the Session Level]].
  
  
  
 
===Sequencing and Preallocation Size===
 
===Sequencing and Preallocation Size===
 
 
To improve sequencing efficiency, EclipseLink lets you preallocate sequence numbers. Preallocation enables EclipseLink to build a pool of available sequence numbers that are assigned to new objects as they are created and inserted into the database. EclipseLink assigns numbers from the sequence pool until the pool is empty.
 
To improve sequencing efficiency, EclipseLink lets you preallocate sequence numbers. Preallocation enables EclipseLink to build a pool of available sequence numbers that are assigned to new objects as they are created and inserted into the database. EclipseLink assigns numbers from the sequence pool until the pool is empty.
  
Line 330: Line 300:
 
For table sequencing, EclipseLink maintains a pool of preallocated values for each sequenced class. When EclipseLink exhausts this pool of values, it acquires a new pool of values, as follows:
 
For table sequencing, EclipseLink maintains a pool of preallocated values for each sequenced class. When EclipseLink exhausts this pool of values, it acquires a new pool of values, as follows:
  
# EclipseLink accesses the database, requesting that the <tt>SEQ_COUNT</tt> for the given class (identified by the <tt>SEQ_NAME</tt>) be incremented by the preallocation size and the result returned.For example, consider the <tt>SEQUENCE</tt> table in [[#Figure 23-2| EclipseLink Table Sequence Table]]. If you create a new purchase order and EclipseLink has exhausted its pool of sequence numbers, then EclipseLink executes a SQL statement to increment <tt>SEQ_COUNT</tt> for <tt>SEQ_PURCH_ORDER</tt> by the preallocation size (in this case, the EclipseLink default of <tt>50</tt>). The database increments <tt>SEQ_COUNT</tt> for <tt>SEQ_PURCH_ORDER</tt> to <tt>1600</tt> and returns this number to EclipseLink.
+
# EclipseLink accesses the database, requesting that the <tt>SEQ_COUNT</tt> for the given class (identified by the <tt>SEQ_NAME</tt>) be incremented by the preallocation size and the result returned.<br>For example, consider the <tt>SEQUENCE</tt> table in the [[#Figure 23-2| EclipseLink Table Sequence Table]] figure. If you create a new purchase order and EclipseLink has exhausted its pool of sequence numbers, then EclipseLink executes a SQL statement to increment <tt>SEQ_COUNT</tt> for <tt>SEQ_PURCH_ORDER</tt> by the preallocation size (in this case, the EclipseLink default of <tt>50</tt>). The database increments <tt>SEQ_COUNT</tt> for <tt>SEQ_PURCH_ORDER</tt> to <tt>1600</tt> and returns this number to EclipseLink.
 
# EclipseLink calculates a maximum and a minimum value for the new sequence number pool, and creates the pool of values.
 
# EclipseLink calculates a maximum and a minimum value for the new sequence number pool, and creates the pool of values.
 
# EclipseLink populates the object sequence attribute with the first number in the pool and writes the object to the class table.
 
# EclipseLink populates the object sequence attribute with the first number in the pool and writes the object to the class table.
Line 352: Line 322:
 
[[Category: Draft]]
 
[[Category: Draft]]
 
[[Category: Concept]]
 
[[Category: Concept]]
 +
[[Category: ORM]]

Revision as of 11:08, 14 December 2007

This section provides an overview of relational projects and focuses on building these projects for relational and object-relational data type databases.

For information on project concepts and features common to more than one type of EclipseLink projects, see Introduction to Projects.


Building Relational Projects

Use a relational project for transactional persistence of Java objects to a conventional relational database or to an object-relational data type database that supports data types specialized for object storage, both accessed using JDBC.

Note: If you are using Workbench, you must add your JDBC driver to the Workbench classpath. For more information, see Configuring the Workbench Environment.


In a relational project, you can make full use of EclipseLink queries and expressions (see Queries).


How to Build Relational Projects for a Relational Database

The Workbench provides complete support for creating relational projects that map Java objects to a conventional relational database accessed using JDBC.

This table describes the components of a relational project for a relational database.


Components of a Relational Project for a Relational Database

Component Supported Types

Data Source

DatabaseLogin or Database Platforms

Descriptors

Relational Descriptors

Mappings

Relational Mappings (ELUG)


For more information, see Creating a Relational Project.


How to Build Relational Projects for an Object-Relational Data Type Database

The Workbench does not currently support relational projects for an object-relational data type database. You must create such a relational project in Java.

Using Java, you can create a relational project for transactional persistence of Java objects to an object-relational data type database that supports data types specialized for object storage (such as Oracle Database) accessed using JDBC.

When using EclipseLink to build a relational project for an object-relational data type database, consider the following:

  • You must create a Java class and a EclipseLink ObjectRelationalDescriptor for each structured type (Struct/object-type).
  • EclipseLink supports only arrays (Varrays) of basic types or arrays on structured types (Struct/object-type).EclipseLink does not support arrays of Refs or arrays of nested tables.
  • EclipseLink supports only nested tables of Refs.EclipseLink does not support nested tables of basic types, structured types, or array types.

The general development process for building a relational project for an object-relational data type database is as follows:

  1. Define structured object-types in the database.
  2. Define tables of the structured object-types in the database.
  3. Define the Java classes that will map to the structured object-types.
  4. Create a relational project (see Creating a Project).
  5. Create an object-relational data type descriptor for each Java class (see Creating an Object-Relational Data Type Descriptor).
  6. Create object-relational data type mappings from each persistent field of each Java class to the corresponding object-types and object-type tables.
    For more information, see the following:

This table describes the components of a relational project for an object-relational data type database.

Components of a Relational Project for an Object-Relational Data Type Database

Component Supported Types

Data Source

DatabaseLogin or Database Platforms

Descriptors

Object-Relational Data Type Descriptors

Mappings

Object-Relational Data Type Mappings (ELUG)


For more information, see Creating a Relational Project.


Sequencing in Relational Projects

In an relational project, you store persistent objects for your application in database tables that represent the class of instantiated object. As the Sequencing Elements in a Class Database Table figure shows, each row of the VEHICLE_POOL table represents an instantiated object from that class, and the VEH_ID column holds the primary key for each object.


Sequencing Elements in a Class Database Table

Sequencing Elements in a Class Database Table

You configure EclipseLink sequencing at the project or session level (see Configuring Sequencing at the Project Level or Configuring Sequencing at the Session Level) to tell EclipseLink how to obtain values for the primary key column: that is, what type of sequencing to use (see Sequencing Types).

You configure EclipseLink sequencing at the descriptor level (see Configuring Sequencing at the Descriptor Level) to tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created.


Note:When choosing a column type for a primary key value, ensure that the type provides a suitable precision. For example, if you use a TIMESTAMP type but your database platform's TIMESTAMP is defined only to the second, then identical values may be returned for objects created within the same second.


This section describes the following:


Sequencing Configuration Options

You can configure sequencing using either the Workbench or Java (but not both).

Using the Workbench, create one sequence with a single preallocation size that applies to all descriptors that require sequencing. You can configure table sequencing (see Table Sequencing) or native sequencing (see Native Sequencing with an Oracle Database Platform). If you choose table sequencing, you can either use default table and column names or specify your own (see Default Versus Custom Sequence Table).

Using Java, you can configure any sequence type that EclipseLink supports (see Sequencing Types). You can create any number and combination of sequences per project. You can create a sequence object explicitly or use the platform default sequence (see Default Sequencing). You can associate the same sequence with more than one descriptor or associate different sequences (and different sequence types) to various descriptors. You can configure a separate preallocation size for each descriptor's sequence. For more information, see How to Configure Sequencing at the Session Level Using Java.


Sequencing Types

EclipseLink supports the following sequence types:


Table Sequencing

With table sequencing, you create a single database table that includes sequencing information for one or more sequenced objects in the project. EclipseLink maintains this table to track sequence numbers for these object types.

As the EclipseLink Table Sequence Table figure shows, the table may contain sequencing information for more than one class that uses sequencing. The default table is called SEQUENCE and contains two columns:

  • SEQ_NAME, which specifies the class type to which the selected row refers
  • SEQ_COUNT, which specifies the highest sequence number currently allocated for the object represented in the selected row


EclipseLink Table Sequence Table

EclipseLink Table Sequence Table

The rows of the SEQUENCE table represent each sequence object: one for each class that participates in sequencing or a single sequence object across several classes so that they can benefit from the same preallocation pool. When you configure sequencing at the descriptor level (see Configuring Sequencing at the Descriptor Level), you specify the SEQ_NAME for the class. Add a row with that name to the SEQUENCE table and initialize the SEQ_COUNT column to the value .

Each time a new instance of a class is created, EclipseLink obtains the required sequence value. For efficiency, EclipseLink uses preallocation to reduce the number of table accesses required to obtain sequence values (see Sequencing and Preallocation Size).

You can create the SEQUENCE table on the database in one of two ways:

You can configure table sequencing using the Workbench or Java. For more information about configuring table sequencing, see Configuring Sequencing at the Project Level or Configuring Sequencing at the Session Level.


Default Versus Custom Sequence Table

In most cases, you implement table sequencing using the default table and column names. However, you may want to specify your own table and column names if the following holds true:

  • You want to use an existing sequence table for sequencing.
  • You do not want to use the default naming convention for the table and its columns.


Unary Table Sequencing

Although similar to table sequencing (see Table Sequencing), with unary table sequencing, you create a separate sequence table for each sequenced object in the project.

As this figure shows, sequencing information appears in the table for a single class that uses sequencing. You can name the table anything you want but it must contain only one column named (by default) SEQUENCE.


EclipseLink Unary Table Sequence Table

EclipseLink Unary Table Sequence Table

When you configure sequencing at the descriptor level, you specify the sequence name for the class: this is the name of the unary table sequence table. The EclipseLink Unary Table Sequence Table figure shows a unary table sequence for the Employee class. The Employee class descriptor is configured (see Configuring Sequencing at the Descriptor Level) with a sequence name of EMP_SEQ to match the unary table sequence table name. EclipseLink adds a row to this table and initializes the SEQUENCE column to the value 1.

Each time a new class is created, EclipseLink obtains the required sequence value from the single row of the unary sequence table corresponding to the class. For efficiency, EclipseLink uses preallocation to reduce the number of table accesses required to obtain sequence values (see Sequencing and Preallocation Size).

You can create the unary table sequence table on the database in one of two ways:

Currently, you can only configure unary table sequencing in Java using the UnaryTableSequence class (for more information, see How to Configure Sequencing at the Session Level Using Java).


Query Sequencing

With query sequencing, you can access a sequence resource using custom read (ValueReadQuery) and update (DataModifyQuery) queries and a preallocation size that you specify. This allows you to perform sequencing using stored procedures and allows you to access sequence resources that are not supported by the other sequencing types that EclipseLink provides.

Currently, you can only configure query sequencing in Java using the QuerySequence class (for more information, see Configuring Query Sequencing).


Default Sequencing

The platform owned by a login is responsible for providing a default sequence instance appropriate for the platform type. For example, by default, a DatabasePlatform provides a table sequence using the default table and column names (see Table Sequencing).

You can access this default sequence directly using DatasourceLogin method getDefaultSequence, or indirectly by using the DefaultSequence class, a wrapper for the platform default sequence.

If you associate a descriptor with a nonexistent sequence, the EclipseLink runtime will create an instance of DefaultSequence to provide sequencing for that descriptor. For more information, see Configuring the Platform Default Sequence.

The main purpose of the DefaultSequence is to allow a sequence to use a different pre-allocation size than the project default.

Currently, you can only make use of default sequencing in Java (for more information, see Using the Platform Default Sequence).


Native Sequencing with an Oracle Database Platform

EclipseLink support for native sequencing with Oracle Databases is similar to table sequencing (see Table Sequencing), except that EclipseLink does not maintain a table in the database. Instead, the database contains a sequence object that stores the current maximum number and preallocation size for sequenced objects. The sequence name configured at the descriptor level identifies the sequence object responsible for providing sequencing values for the descriptor's reference class.

You can configure native sequencing using Workbench or Java. For more information about configuring table sequencing, see Configuring Sequencing at the Project Level or Configuring Sequencing at the Session Level.


Understanding the Oracle SEQUENCE Object

The Oracle SEQUENCE object implements a strategy that closely resembles EclipseLink sequencing: it implements an INCREMENT construct that parallels the EclipseLink preallocation size, and a sequence.nextval construct that parallels the SEQ_COUNT field in the EclipseLink SEQUENCE table in table sequencing. This implementation enables EclipseLink to use the Oracle SEQUENCE object as if it were a EclipseLink SEQUENCE table, but eliminates the need for EclipseLink to create and maintain the table.

As with table sequencing, EclipseLink creates a pool of available numbers by requesting that the Oracle SEQUENCE object increment the sequence.nextval and return the result. Oracle adds the value, INCREMENT, to the sequence.nextval, and EclipseLink uses the result to build the sequencing pool.

The key difference between this process and the process involved in table sequencing is that EclipseLink is unaware of the INCREMENT construct on the SEQUENCE object. EclipseLink sequencing and the Oracle SEQUENCE object operate in isolation. To avoid sequencing errors in the application, set the EclipseLink preallocation size and the Oracle SEQUENCE object INCREMENT to the same value. Note that the Oracle sequence object must have a starting value equal to the preallocation size because when EclipseLink gets the next sequence value, it assume it has the previous preallocation size of values.


Using SEQUENCE Objects

Your database administrator (DBA) must create a SEQUENCE object on the database for every sequencing series your application requires. If every class in your application requires its own sequence, the DBA creates a SEQUENCE object for every class; if you design several classes to share a sequence, the DBA need create only one SEQUENCE object for those classes.

For example, in the Example of Database Tables–Racquet Information figure, consider the case of a sporting goods manufacturer that manufactures three styles of tennis racquet. The data for these styles of racquet are stored in the database as follows:

  • Each style of racquet has its own class table.
  • Each manufactured racquet is an object represented by a line in the class table.
  • The system assigns serial numbers to the racquets that use sequencing.


Example of Database Tables–Racquet Information

Example of Database Tables–Racquet Information

The manufacturer can do either of the following:

  • Use separate sequencing for each racquet style. The DBA builds three separate SEQUENCE objects, perhaps called ATTACK_SEQ, VOLLEY_SEQ, and PROX_SEQ. Each different racquet line has its own serial number series, and there may be duplication of serial numbers between the lines (for example: all three styles may include a racquet with serial number 1234).
  • Use a single sequencing series for all racquets. The DBA builds a single SEQUENCE object (perhaps called RACQUET_SEQ). The manufacturer assigns serial numbers to racquets as they are produced, without regard for the style of racquet.


Native Sequencing with a Non-Oracle Database Platform

Several databases support a type of native sequencing in which the database management system generates the sequence numbers.

When you create a database table for a class that uses native sequencing, include a primary key column, and set the column type as follows:

  • For Sybase and Microsoft SQL Server databases, set the primary key field to the type IDENTITY.
  • For IBM Informix databases, set the primary key field to the type SERIAL.
  • For IBM DB2 databases, set the primary key field to the type IDENTITY.

When you insert a new object into the table, EclipseLink populates the object before insertion into the table, but does not include the sequence number. As the database inserts the object into its table, the database automatically populates the primary key field with a value equal to the primary key of the previous object plus 1.

At this point, and before the transaction closes, EclipseLink reads back the primary key for the new object so that the object has an identity in the EclipseLink cache.


Note: This type of sequencing does not support preallocation, so the preallocation size must be set to 1. To take advantage of sequence preallocation, we recommend that you use table sequencing on these databases instead of native sequencing.


If your database provides native sequencing, but EclipseLink does not directly support it, you may be able to access the native sequence object using a query sequence and stored procedures. For more information, see Query Sequencing.

You can configure native sequencing using Workbench or Java. We recommend that you use the Workbench. For more information about configuring table sequencing, see Configuring Sequencing at the Project Level or Configuring Sequencing at the Session Level.


Sequencing and Preallocation Size

To improve sequencing efficiency, EclipseLink lets you preallocate sequence numbers. Preallocation enables EclipseLink to build a pool of available sequence numbers that are assigned to new objects as they are created and inserted into the database. EclipseLink assigns numbers from the sequence pool until the pool is empty.

The preallocation size specifies the size of the pool of available numbers. Preallocation improves sequencing efficiency by substantially reducing the number of database accesses required by sequencing. By default, EclipseLink sets preallocation size to 50. You can specify preallocation size either in the Workbench or as part of the session login.

Preallocation size configuration applies to table sequencing and Oracle native sequencing. In Oracle native sequencing, the sequence preallocation size must match the Oracle sequence object increment size. Preallocation is not available for native sequencing in other databases as they use an auto-assigned sequence column. We recommend that you use table sequencing in non-Oracle databases to allow preallocation.

For table sequencing, EclipseLink maintains a pool of preallocated values for each sequenced class. When EclipseLink exhausts this pool of values, it acquires a new pool of values, as follows:

  1. EclipseLink accesses the database, requesting that the SEQ_COUNT for the given class (identified by the SEQ_NAME) be incremented by the preallocation size and the result returned.
    For example, consider the SEQUENCE table in the EclipseLink Table Sequence Table figure. If you create a new purchase order and EclipseLink has exhausted its pool of sequence numbers, then EclipseLink executes a SQL statement to increment SEQ_COUNT for SEQ_PURCH_ORDER by the preallocation size (in this case, the EclipseLink default of 50). The database increments SEQ_COUNT for SEQ_PURCH_ORDER to 1600 and returns this number to EclipseLink.
  2. EclipseLink calculates a maximum and a minimum value for the new sequence number pool, and creates the pool of values.
  3. EclipseLink populates the object sequence attribute with the first number in the pool and writes the object to the class table.

As you add new objects to the class table, EclipseLink continues to assign values from the pool until it exhausts the pool. When the pool is exhausted, EclipseLink again requests new values from the table.

Using the Workbench, you specify a preallocation size when you choose a sequencing type at the project or session level. That preallocation size applies to all descriptors.

Using Java, you can specify a different preallocation size for each sequence that you create.

For more information about configuring preallocation size, see Configuring Sequencing at the Project Level or Configuring Sequencing at the Session Level.




Copyright Statement

Back to the top