|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
 Previous |
 Next |
|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
|
Previous |
Next |
Sequencing allows TopLink to automatically assign the primary key or ID of an object when the object is inserted.
You configure TopLink sequencing at the project level ("Configuring Sequencing at the Project Level") or session level ("Configuring Sequencing at the Session Level") to tell TopLink how to obtain sequence values: that is, what type of sequences to use.
To enable sequencing, you must then configure TopLink sequencing at the descriptor level to tell TopLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created.
Only descriptors that have been configured with a sequence field and a sequence name will be assigned sequence numbers.
The sequence field is the database field that the sequence number will be assigned to: this is almost always the primary key field (see "Configuring Primary Keys"). The sequence name is the name of the sequence to be used for this descriptor. The purpose of the sequence name depends on the type of sequencing you are using:
When using table sequencing, the sequence name refers to the row's SEQ_NAME value used to store this sequence.
When using Oracle native sequencing, the sequence name refers to the Oracle sequence object that has been created in the database. When using native sequencing on other databases, the sequence name does not have any direct meaning, but should still be set for compatibility.
The sequence name can also refer to a custom sequence defined in the project.
For more information, see "Understanding Sequencing in Relational Projects".
To configure sequencing for a descriptor, use this procedure:
Select a descriptor in the Navigator. Its properties appear in the Editor.
Click the Descriptor Info tab. The Descriptor Info tab appears.
Figure 29-2 Descriptor Info Tab, Sequencing Options
Use the following information to specify sequencing options:
| Field | Description |
|---|---|
| Use Sequencing | Specify if this descriptor uses sequencing. If selected, specify the Name, Table, and Field for sequencing. |
| Name | Enter the name of the sequence.
|
| Table | Specify the name of the database table that contains the field (see Field) into which TopLink is to write the sequence value when a new instance of this descriptor's reference class is created. This is almost always this descriptor's primary table. |
| Field | Specify the name of the field in the specified table (see Table) into which TopLink is to write the sequence value when a new instance of this descriptor's reference class is created. This field is almost always the class's primary key (see "Configuring Primary Keys").
|
Using Java, you can configure sequencing to use multiple different types of sequence for different descriptors. You configure the sequence objects on the session's login and reference them from the descriptor by their name. The descriptor's sequence name refers to the sequence object's name you register in the session's login.
The following examples assume the session sequence configuration shown in Example 29-1.
Example 29-1 Example Sequences
dbLogin.addSequence(new TableSequence("EMP_SEQ", 25));
dbLogin.addSequence(new DefaultSequence("PHONE_SEQ", 30));
dbLogin.addSequence(new UnaryTableSequence("ADD_SEQ", 55));
dbLogin.addSequence(new NativeSequence("NAT_SEQ", 10));
Using Java code, you can perform the following sequence configurations:
As Example 29-2 shows, you associate a sequence with a descriptor by sequence name. The sequence EMP_SEQ was added to the login for this project in Example 29-1. When a new instance of the Employee class is created, the TopLink runtime will use the sequence named EMP_SEQ (in this example, a TableSequence) to obtain a value for the EMP_ID field.
As Example 29-3 shows, you can associate the same sequence with more than one descriptor. In this example, both the Employee descriptor and Phone descriptor use the same NativeSequence. Having descriptors share the same sequence can improve pre-allocation performance. For more information on pre-allocation, see "Sequencing and Preallocation Size".
Example 29-3 Configuring a Sequence for Multiple Descriptors
empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field
empDescriptor.setSequenceNumberName("NAT_SEQ");
phoneDescriptor.setSequenceNumberFieldName("PHONE_ID"); // primary key field
phoneDescriptor.setSequenceNumberName("NAT_SEQ");
In Example 29-4, you associate a nonexistent sequence (NEW_SEQ) with a descriptor. Because you did not add a sequence named NEW_SEQ to the login for this project in Example 29-1, the TopLink runtime will create a DefaultSequence named NEW_SEQ for this descriptor. For more information about DefaultSequence, see "Default Sequencing".
