Database Login Information

Java applications that access a database log in to the database through a JDBC driver. Database logins usually require a valid user name and password. OracleAS TopLink applications store this login information in the DatabaseLogin class. All sessions must have a valid DatabaseLogin instance before logging in to the database.

This section describes:

Creating a Login Object
Specifying Driver Information
Setting Login Parameters
Database Login Advanced Features

Creating a Login Object

Your project configuration file (project.xml or project.java) must include a login object to enable database access. The most basic login mechanism creates an instance of DatabaseLogin through its default constructor, as follows:

Databaselogin login = new Databaselogin();
...

If you create the project in OracleAS TopLink Mapping Workbench, then OracleAS TopLink creates the login object for you automatically and enables you to access the login from your project instance. This ensures that the session uses login information set in OracleAS TopLink Mapping Workbench (for example, sequencing information) and also prevents you from inadvertently overwriting the login information already included in the project.

You can also access the login in Java code, using the getLogin() instance method to return the project login. This method returns an instance of DatabaseLogin, which you can either use directly or augment with additional information before logging in.

Specifying Driver Information

The DatabaseLogin class includes helper methods that set the driver class, driver Uniform Resource Locator (URL) prefix, and database information for common drivers. When you use helper methods, use the setDatabaseURL() method to set the database instance for the JDBC driver URL.

These helper methods also specify any additional settings required for that driver, such as binding byte arrays or using native SQL.

For example:

project.getLogin().useOracleThinJDBCDriver();
project.getLogin().setDatabaseURL("dbserver:1521:orcl");

Using the Sun Microsystems JDBC-ODBC Bridge

To use the Sun Microsystems JDBC-ODBC bridge, specify the ODBC datasource name by calling the setDataSourceName().

Example 5-3 Using the Sun Microsystems JDBC-ODBC Bridge

project.getLogin().useJDBCODBCBridge();
project.getLogin().useOracle();
project.getLogin().setDataSourceName("Oracle");

In Example 5-3, OracleAS TopLink splits the URL into the driver and database calls. You can also use the setConnectionString() function to specify the URL in a single line of code.

Using a Different Driver

If you require a driver other than the Sun Microsystems JDBC-ODBC bridge, specify a different connection mechanism by calling the setDriverClass() and setConnectionString() methods.

For more information about the correct driver settings to use with these methods, see the driver documentation.

Example 5-4 Using an Alternative Driver

project.getLogin().setDriverClass(oracle.jdbc.driver.OracleDriver.class);
project.getLogin().setConnectionString("jdbc:oracle:thin:@dbserver:1521:orcl");

Setting Login Parameters

You can set several session properties as part of the login, including user information, database information, and JDBC driver information.

User Information

If a database requires user and password information, call the setUserName() and setPassword() methods after you specify the driver. Specify user and password information when you use the login object from an OracleAS TopLink Mapping Workbench project.

Example 5-5 Using setUserName() and setPassword()

project.getLogin().setUserName("userid");
project.getLogin().setPassword("password");

Database Information

You can specify properties such as the database name and the server name using the setServerName() and setDatabaseName() methods. The ODBC datasource Administrator for most JDBC-ODBC bridges usually sets these properties, but some drivers do require you to specify them explicitly.

Note that, because the database and server name properties are part of the database URL, most JDBC drivers do not require you to specify them explicitly and may fail if you do specify them.

Additional JDBC Properties

If your JDBC driver requires additional properties, use the setProperty() method to send these properties. Use caution when specifying properties, because, although some drivers require additional information, other drivers can fail if you specify properties that are not required. If you use the setProperty() method and the connection always fails, ensure that the specified properties are correct, complete, and required.

Note:

Do not set the login password directly using the setProperty() method, because OracleAS TopLink encrypts and decrypts the password. Use the setPassword() method instead.

Database Login Advanced Features

You can set the following options within your code, rather than through OracleAS TopLink Mapping Workbench:

Setting Sequencing at Login
Setting Direct Connect Drivers
Using JDBC 2.0 Datasources
Using Custom Database Connections

There are several options you can set at login rather than through more conventional methods, such as through OracleAS TopLink Mapping Workbench.

Setting Sequencing at Login

For most projects, you set sequencing in OracleAS TopLink Mapping Workbench project. To configure sequencing in Java code, you can use any of the following methods:

setSequenceCounterFieldName()
setSequenceNameFieldName()
setSequencePreallocationSize()
setSequenceTableName()
useNativeSequencing()

OracleAS TopLink supports native sequencing on Oracle databases, IBM Informix, Microsoft SQL Server, and Sybase SQL Server. Using native sequencing requires that you specify the database platform. Call the useNativeSequencing() method to configure your application to use native sequencing rather than a sequence table.

When you implement native sequencing, note the following:

The sequence preallocation size defaults to 1. If you use Sybase SQL Server, Microsoft SQL Server, or IBM Informix native sequencing, you cannot use preallocation and you cannot change the size.

When using native sequencing with Oracle, specify the name of the sequence object (the object that generates the sequence numbers) for each descriptor. The sequence preallocation size must also match the increment on the sequence object.

Notes:

Ensure that you match the increment of the Oracle sequence and not the cache. The cache refers to the sequences cached on the database server; the increment refers to the number of sequences that can be cached on the database client.
When you use sequencing or native sequencing, specify the sequence information in each descriptor that makes use of a generated ID.
Use preallocation and native sequencing for Oracle databases.

Example 5-6 Configuring Oracle Native Sequencing in Java Code

project.getLogin().useOracle();
project.getLogin().useNativeSequencing();
project.getLogin().setSequencePreallocationSize(1);

Note:

Employing the Project class to create a DatabaseLogin instance automatically uses the sequencing information specified in OracleAS TopLink Mapping Workbench.

For more information, see "Sequencing".

Setting Direct Connect Drivers

By default, OracleAS TopLink loads a JDBC driver and connects to a database as follows:

To load and initialize the class, OracleAS TopLink calls java.lang.Class.forName().
To obtain a connection, OracleAS TopLink calls java.sql.DriverManager.getConnection().

Some drivers do not allow you to use the java.sql.DriverManager to connect to a database. To load these drivers, configure OracleAS TopLink to instantiate the drivers directly, by invoking the DirectDriverConnect() method.

Example 5-7 Using useDirectDriverConnect()

project.getLogin().useDirectDriverConnect("com.direct.connectionDriver",
  "jdbc:far:", "server");

Using JDBC 2.0 Datasources

The JDBC 2.0 specification recommends using a Java Naming and Directory Interface (JNDI) naming service to acquire a connection to a database. To use this feature, configure an instance of oracle.toplink.jndi.JNDIConnector, and pass it to the project login object using the setConnector() method.

Example 5-8 Using JNDI

import oracle.toplink.sessions.*;
import oracle.toplink.jndi.*;

javax.naming.Context context = new javax.naming.InitialContext();
Connector connector = new JNDIConnector(context, "customerDB");
project.getLogin().setConnector(connector);

Using Custom Database Connections

OracleAS TopLink allows you to develop your own class to obtain a connection to a database. The class must implement the oracle.toplink.sessions.Connector interface. This requires the class to implement the following methods:

java.sql.Connection connect(java.util.Properties properties): Receives a dictionary of properties (including the user name and password), and must return a valid connection to the database
void toString(PrintWriter writer): Prints out any helpful information on the OracleAS TopLink log

Implement the custom class, instantiate it, and then pass it to the project login object, using the setConnector() method.

Example 5-9 Using the oracle.toplink.sessions.Connector Interface

import oracle.toplink.sessions.*;

Connector connector = new MyConnector();
project.getLogin().setConnector(connector);