Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Configuring Sequencing at the Descriptor Level

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".

## Using TopLink Workbench

To configure sequencing for a descriptor, use this procedure:

1. Select a descriptor in the Navigator. Its properties appear in the Editor.

2. Click the Descriptor Info tab. The Descriptor Info tab appears.

   Figure 29-2 Descriptor Info Tab, Sequencing Options

   Description of "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. For table sequencing: Enter the name of the value in the sequence name column (for default table sequencing, the column named `SEQ_NAME`) of the sequence table (for default table sequencing, the table named `SEQUENCE`) that TopLink uses to look up the corresponding sequence count value (for default table sequencing, the corresponding value in the `SEQ_COUNT` column) for this descriptor's reference class. For more information, see "Table Sequencing". For native sequencing (Oracle platform): Enter the name of the sequence object that Oracle Database creates to manage sequencing for this descriptor's reference class. For more information, see "Native Sequencing With an Oracle Database Platform" For native sequencing (non-Oracle platform): For database compatibility, enter a generic name for the sequence, such as `SEQ`. For more information, see "Native Sequencing With a Non-Oracle Database Platform".
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"). For native sequencing (non-Oracle platform): Ensure that your database schema specifies the correct type for this field (see "Native Sequencing With a Non-Oracle Database Platform").

## Using Java

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:

- Configuring a Sequence by Name

- Configuring the Same Sequence for Multiple Descriptors

- Configuring the Platform Default Sequence

### Configuring a Sequence by Name

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.

Example 29-2 Associating a Sequence with a Descriptor

    empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field
    empDescriptor.setSequenceNumberName("EMP_SEQ");

### Configuring the Same Sequence for Multiple Descriptors

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");

### Configuring the Platform Default Sequence

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".

Example 29-4 Configuring a Default Sequence

    descriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field
    descriptor.setSequenceNumberName("NEW_SEQ");