20 Configuring a Relational Project

This chapter describes the various components that you must configure in order to use a relational project.

This chapter contains the following sections:

This chapter also describes logging into a database during development when using TopLink Workbench. For more information, see Section 20.6, "Logging In to the Database".

For information on how to configure TopLink project options common to two or more project types, see Chapter 117, "Configuring a Project".

Table 20-1 lists the configurable options for relational projects.

This chapter also describes logging in to a database during development when using TopLink Workbench. For more information, see Section 20.6, "Logging In to the Database".

20.1 Introduction to Relational Project Configuration

In addition to the configurable options described here, you must also configure the base class options described in Table 117-2, "Common Project Options".

Table 20-1 lists the configurable options for relational projects.

Table 20-1 Configurable Options for Relational Projects

Option to Configure Oracle JDeveloper
TopLink Workbench Java

Project save location (see Section 117.2, "Configuring Project Save Location")

Unsupported Supported Unsupported

Persistence type (see Section 117.5, "Configuring Persistence Type")

Supported Supported Unsupported

Project classpath (see Section 117.3, "Configuring Project Classpath")

Unsupported Supported Unsupported

Project comments (see Section 117.14, "Configuring Project Comments")

Supported Supported Unsupported

Method or direct field access (see Section 117.4, "Configuring Method or Direct Field Access at the Project Level")

Supported Supported Supported

Default descriptor advanced properties (see Section 117.6, "Configuring Default Descriptor Advanced Properties")

Supported Supported Supported

Existence checking (see Section 117.7, "Configuring Existence Checking at the Project Level")

Supported Supported Supported

Project deployment XML options (see Section 117.8, "Configuring Project Deployment XML Options")

Unsupported Supported Supported

Model Java source code options (see Section 117.9, "Configuring Model Java Source Code Options")

Supported Supported Supported

Relational database (see Section 20.2, "Configuring Relational Database Platform at the Project Level")

Supported Supported Supported

Sequencing (see Section 20.3, "Configuring Sequencing at the Project Level")

Supported Supported Supported

Login information (see Section 20.4, "Configuring Login Information at the Project Level")

Supported Supported Supported

Development and deployment logins (see Section 20.5, "Configuring Development and Deployment Logins")

Supported Supported Unsupported

Cache type and size (see Section 117.10, "Configuring Cache Type and Size at the Project Level")

Supported Supported Supported

Cache isolation (see Section 117.11, "Configuring Cache Isolation at the Project Level")

Supported Supported Supported

Cache coordination change propagation (see Section 117.12, "Configuring Cache Coordination Change Propagation at the Project Level")

Supported Supported Supported

Cache expiration (see Section 117.13, "Configuring Cache Expiration at the Project Level")

Supported Supported Unsupported

Named query parameterized SQL and statement caching (see Section 20.7, "Configuring Named Query Parameterized SQL and Statement Caching at the Project Level")

Supported Supported Unsupported

Table generation options (see Section 20.8, "Configuring Table Generation Options")

Unsupported Supported Unsupported

Table creator Java source options (see Section 20.9, "Configuring Table Creator Java Source Options")

Unsupported Supported Unsupported

Project Java source code options (see Section 20.10, "Configuring Project Java Source Code Options")

Unsupported Supported Unsupported

Deprecated direct mappings (see Section 20.11, "Configuring Deprecated Direct Mappings")

Supported Supported Unsupported

For more information, see Chapter 18, "Introduction to Relational Projects".

20.2 Configuring Relational Database Platform at the Project Level

For each relational project, you must specify the database platform (such as Oracle Database 10g). This platform configuration is overridden by the session login, if configured.

For more information, see the following:

20.2.1 How to Configure Relational Database Platform at the Project Level Using TopLink Workbench

To specify the database platform of a relational project, use this procedure:

  1. Select the database object in the Navigator. The Database property sheet appears.

    Figure 20-1 Database Property Sheet, Database Platform Options

    Description of Figure 20-1 follows
    Description of "Figure 20-1 Database Property Sheet, Database Platform Options"

Click Change to select a new database platform for the project. For more information, see Section 96.1.3, "Data Source Platform Types".

20.3 Configuring Sequencing at the Project 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 or session level to tell TopLink how to obtain sequence values: that is, what type of sequences to use.

In a CMP project, you do not configure a session directly: in this case, you must configure sequences at the project level. In a POJO project, you can configure a session directly: in this case, you can use a session-level sequence configuration to override project-level sequence configuration, on a session-by-session basis, if required (see Section 98.4, "Configuring Sequencing at the Session Level").

You can configure sequencing using Oracle JDeveloper.

Using TopLink Workbench (see Section 20.3.1, "How to Configure Sequencing at the Project Level Using TopLink Workbench"), you can configure table sequencing (see Section 18.2.2.1, "Table Sequencing") and native sequencing (Section 18.2.2.5, "Native Sequencing with an Oracle Database Platform" and Section 18.2.2.6, "Native Sequencing with a Non-Oracle Database Platform") and you can configure a preallocation size that applies to all sequences (see Section 18.2.3, "Sequencing and Preallocation Size").

Using Java (see Section 20.3.2, "How to Configure Sequencing at the Project Level Using Java"), you can configure any sequence type that TopLink supports (Section 18.2.2, "Sequencing Types"). You can create any number and combination of sequences. You can create a sequence object explicitly or use the default sequence that the platform creates. You can associate the same sequence with more than one descriptor and you can configure a separate preallocation size for each descriptor's sequence.

After configuring the sequence type at the project (or session) level, to enable sequencing, you must configure a descriptor with a sequence field and a sequence name (see Section 23.3, "Configuring Sequencing at the Descriptor Level").

For more information about sequencing, see Section 18.2, "Sequencing in Relational Projects".

20.3.1 How to Configure Sequencing at the Project Level Using TopLink Workbench

To specify the sequencing information for the project, use this procedure:

  1. Select the project object in the Navigator.

  2. Select the Sequencing tab in the Editor. The Sequencing tab appears.

    Figure 20-2 Sequencing Tab

    Description of Figure 20-2 follows
    Description of "Figure 20-2 Sequencing Tab"

Use this table to enter data in the following fields to configure the sequencing information:

Field Description
Preallocation Size Specify the default preallocation size (see Section 18.2.3, "Sequencing and Preallocation Size"). Default is 50. The preallocation size you configure applies to all sequences.
Default Sequence Table Select this option to use table sequencing (see Section 18.2.2.1, "Table Sequencing") with default sequence table name SEQUENCE, default sequence name field SEQ_NAME, and default sequence counter field SEQ_COUNT.
Native Sequencing Select this option to use a sequencing object (see Section 18.2.2.5, "Native Sequencing with an Oracle Database Platform" or Section 18.2.2.6, "Native Sequencing with a Non-Oracle Database Platform") created by the database platform. This option applies only to Oracle, Sybase, Microsoft SQL, and IBM Informix database platforms.
Custom Sequence Table Select this option to use table sequencing (see Section 18.2.2.1, "Table Sequencing") with a sequence table name, sequence name field, and sequence counter field name that you specify.
    Name Specify the name of the sequence table.
    Name Field Specify the name of the column used to store the sequence name.
    Counter Field Specify the name of the column used to store the sequence count.

20.3.2 How to Configure Sequencing at the Project Level Using Java

Using Java, you can configure a project to use multiple, different sequences, as Example 20-1 shows.

Example 20-1 Configuring Sequencing at the Project Level in Java

// Enable native sequencing for the project as the default. Configured the default    
// preallocation size
project.getLogin().useNativeSequencing();
project.getLogin().setSequencePreallocationSize(50);

// Configure the EMP_SEQ to not use preallocation
DefaultSequence empSequence = new DefaultSequence("EMP_SEQ", 1);
project.getLogin().addSequence(empSequence);

// Configure the PROJ_SEQ to use a seperate sequence table
UnarySequence projSequence = new UnarySequence("PROJ_SEQ_TAB", "COUNTER");
project.getLogin().addSequence(projSequence);

20.4 Configuring Login Information at the Project Level

This section describes how to define a login to a relational database. After you define a login, you must designate its role (see Section 20.5, "Configuring Development and Deployment Logins").

After you create a login (see Section 20.4, "Configuring Login Information at the Project Level") and specify it as a development login (see Section 20.5, "Configuring Development and Deployment Logins"), you can log in to a database instance (see Section 20.6, "Logging In to the Database").

20.4.1 How to Configure Login Information at the Project Level Using TopLink Workbench

To create or edit a database login, use this procedure:

  1. Select the database object in the Navigator. The Database property sheet appears.

    Figure 20-3 Database Property Sheet, Database Login Fields

    Description of Figure 20-3 follows
    Description of "Figure 20-3 Database Property Sheet, Database Login Fields"

  2. Click Add to create a new Defined Login.

  3. Complete the Database Login fields on the property sheet.

Use this table to enter data in the following fields on the Database property sheet to configure the database login:

Field Description
Defined Logins Login used to access the database. Click Add to add a new login, or Remove to delete an existing login.
Driver Class The JDBC driver to use to connect to the database.
URL The URL used to connect to the appropriate database.
User Name The name required to log in to the database.
Password The password required to log in to the database.
    Save Password Whether or not to save the Password for this Defined Login.

Oracle recommends that you do not save the password with a deployment login.

Note: If you select Save Password, then when you export Java source and deployment XML (see Section 116.3, "Exporting Project Information"), TopLink Workbench writes the database password using JCE encryption (when using JDK 1.4 or later). For information on how to specify password encryption options, see Section 97.3, "Configuring Password Encryption".

Default: unselected.


20.5 Configuring Development and Deployment Logins

This section describes how to designate a defined login's role. For information on how to define a login, see Section 20.4, "Configuring Login Information at the Project Level". TopLink recognizes the following login roles:

Development Role

While using TopLink Workbench to develop a project (see Section 15.2.4.3, "Development Role"), you must define a login (see Section 20.4, "Configuring Login Information at the Project Level") and designate it as the development login. The development login is stored in the TopLink project file. TopLink Workbench use the information in the development login whenever you perform a data source operation from within TopLink Workbench. For example, when you read or write schema information from or to a data source during application development, the development login information is never written to a sessions.xml or project.xml file and is overridden by the deployment login (or the session login) at run time.

For more information on how to use a development login to connect to a database, see Section 20.6, "Logging In to the Database".

CMP Deployment Role

If you are creating a CMP project (see Section 15.2.4.2, "CMP Deployment Role"), you may define a run-time login (see Section 20.4, "Configuring Login Information at the Project Level") and designate it as the deployment login. This is the login that the application will use at run time, unless overridden in the sessions.xml file, CMP deployment file, or through Java code.

POJO Session Role

If you are creating a POJO project (see Section 15.2.4.1, "POJO Session Role"), Oracle recommends that you use the sessions.xml file to store the sessions your project uses at run time (see Section 96.1.2, "Data Source Login Types").

20.5.1 How to Configure Development and Deployment Logins Using TopLink Workbench

To specify different development and deployment database logins, use this procedure:

  1. Select the database object in the Navigator. The Database property sheet appears.

    Figure 20-4 Database Property Sheet, Development and Deployment Login Options

    Description of Figure 20-4 follows
    Description of "Figure 20-4 Database Property Sheet, Development and Deployment Login Options"

Use this table to enter data in the following fields on the Database property sheet to configure the login:

Field Description
Development Login The Defined Login to be used by TopLink Workbench during development to connect with the database, and to read or write table information.

For more information on how to use a development login to connect to a database, see Section 20.6, "Logging In to the Database".

Deployment Login The Defined Login to be used by your TopLink-enabled application during deployment.

20.6 Logging In to the Database

Using Oracle JDeveloper or TopLink Workbench, after you create a login (see Section 20.4, "Configuring Login Information at the Project Level") and specify it as a development login (see Section 20.5, "Configuring Development and Deployment Logins"), you can log in to a database instance.

You must log in to the database before importing or exporting table information.

To log in to the database using TopLink Workbench, use one of the following procedures:

  • Database Login button
    Select the database object in the Navigator and click Login. TopLink Workbench logs in to the database.

  • Right-click on the database object in the Navigator and choose Log In to Database from the context menu, or choose Selected > Log In to Database from the menu.

Database Logged In icon

The database icon in the Navigator window changes to indicate you are now logged in to the database.

20.7 Configuring Named Query Parameterized SQL and Statement Caching at the Project Level

You can configure TopLink to use parameterized SQL (parameter binding) and prepared statement caching for all named queries and finders.

By default, TopLink uses parameterized SQL.

The use of parameterized SQL lets you create and store queries that are complete except for one or more bound parameters. The TopLink runtime binds the current parameter values when executing the query. This approach avoids the preparation of SQL execution and, thus, improves the performance of frequently executed SQL statements.

This section describes configuring parameterized SQL and statement caching options at the project level. This configuration applies to all named queries or finders (see Section 108.8, "Named Queries" or Section 108.15, "EJB 2.n CMP Finders") you create on the descriptors in this project–not to all queries in general or write operations.

You can also configure parameterized SQL and statement caching options at the named query or finder-level to override this project-level configuration on a query-by-query basis (see Section 119.7.1.9, "Configuring Named Query Options") or at the session login-level (see Section 98.6, "Configuring JDBC Options").

For more information, see Section 12.11.5, "How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization".

Note:

For applications using a Java EE data source or external connection pool, you must configure statement caching in the Java EE server's data source–not in TopLink.

Table 20-2 summarizes which projects support parameterized SQL and statement caching configuration.

Table 20-2 Project Support for Default Named Query Caching and Binding

Descriptor How to Use Oracle JDeveloper How to Configure Named Query Parameterized SQL and Statement Caching at the Project Level Using TopLink Workbench
How to Use Java

Relational Projects

Supported.

Supported.

Supported.

EIS Projects

Unsupported Unsupported Unsupported

XML Projects

Unsupported Unsupported Unsupported

20.7.1 How to Configure Named Query Parameterized SQL and Statement Caching at the Project Level Using TopLink Workbench

To specify the named query options, use this procedure:

  1. Select the project object in the Navigator.

  2. Select the Defaults tab in the Editor. The Defaults tab appears.

    Figure 20-5 Defaults Tab, Named Queries Options

    Description of Figure 20-5 follows
    Description of "Figure 20-5 Defaults Tab, Named Queries Options"

Use this table to enter data in following fields on the Defaults tab to specify the named query options for newly created descriptors.:

Field Description
Cache All Statements Caches the query's prepared statement in the TopLink statement cache.
Bind All Parameters By default, TopLink binds all of the query's parameters.

Deselect this option to disable binding.


20.8 Configuring Table Generation Options

Using TopLink Workbench, you can configure options that apply when you generate database tables from the descriptors you define in your TopLink Workbench project. The resulting tables and columns will conform to the naming restrictions of the project's target database.

20.8.1 How to Configure Table Generation Options Using TopLink Workbench

To specify the default table generation options, use this procedure:

  1. Select the project object in the Navigator.

  2. Select the Options tab in the Editor. The Options tab appears.

    Figure 20-6 Options Tab, Table Generation Options

    Description of Figure 20-6 follows
    Description of "Figure 20-6 Options Tab, Table Generation Options"

Use this table to enter data in the following fields to specify the default export and generation options.

Field Description
Default Primary Key Enter the default name to use when generating primary keys.
Primary Key Search Pattern Enter the default search pattern to use when generating primary keys.

20.9 Configuring Table Creator Java Source Options

Using TopLink Workbench, you can configure options that apply when you export Java source code that you can use to create database tables.

20.9.1 How to Configure Table Creator Java Source Options Using TopLink Workbench

To specify the default Java code generation options, use this procedure:

  1. Select the project object in the Navigator.

  2. Select the Options tab in the Editor. The Options tab appears.

    Figure 20-7 Options Tab, Table Creator Java Source Options

    Description of Figure 20-7 follows
    Description of "Figure 20-7 Options Tab, Table Creator Java Source Options"

Use this table to enter data in the following fields to specify the default table creator options.

Field Description
Class Name Base class name to use when generating table's Java source code from the project.
Root Directory Directory for storing the generated source code.

20.10 Configuring Project Java Source Code Options

Using TopLink Workbench, you can export a project as Java source. You can configure the class name and root directory that TopLink Workbench uses when exporting the project to Java source code.

For more information on exporting a project as Java source, see Section 19.6.1, "How to Export Project Java Source Using TopLink Workbench".

20.10.1 How to Configure Project Java Source Code Options Using TopLink Workbench

To specify the default Java code generation options, use this procedure:

  1. Select the project object in the Navigator.

  2. Select the Options tab in the Editor. The Options tab appears.

    Figure 20-8 Options Tab, Project Java Source Options

    Description of Figure 20-8 follows
    Description of "Figure 20-8 Options Tab, Project Java Source Options"

Use this table to enter data in the following fields to specify the default export and generation options:

Field Description
Class Name Base class name to use when generating Java source code from the project.
Root Directory Directory for storing the generated source code.

20.11 Configuring Deprecated Direct Mappings

You can configure deprecated direct mapping options when using Oracle JDeveloper or TopLink Workbench.

Starting with the 10.1.3.1 release, TopLink no longer uses the following direct mapping types:

  • Type conversion

  • Object type

  • Serialized object

Instead, TopLink uses a direct-to-field mapping with a specialized converter.

To generate backward-compatible deployment XML and Java source code files, use the Generate Deprecated Direct Mappings option.

20.11.1 How to Configure Deprecated Direct Mappings Using TopLink Workbench

To specify if TopLink Workbench should generate the deprecated direct mappings (instead of using the converter) when exporting projects, use this procedure:

  1. Select the project object in the Navigator.

  2. Select the Options tab in the Editor. The Options tab appears.

    Figure 20-9 Options Tab, Generate Deprecated Direct Mappings Option

    Description of Figure 20-9 follows
    Description of "Figure 20-9 Options Tab, Generate Deprecated Direct Mappings Option"

Select the Generate Deprecated Direct Mappings option on the tab to specify that TopLink Workbench should generate backward-compatible code (using the deprecated direct mappings, instead of the converter).