Oracle® Application Server TopLink Application Developer's Guide
10g Release 2 (10.1.2)
Part No. B15901-01
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:
Your project configuration file (
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
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.
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.
To use the Sun Microsystems JDBC-ODBC bridge, specify the ODBC datasource name by calling the
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.
For more information about the correct driver settings to use with these methods, see the driver documentation.
You can set several session properties as part of the login, including user information, database information, and JDBC driver information.
If a database requires user and password information, call the
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.
You can specify properties such as the database name and the server name using the
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.
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
You can set the following options within your code, rather than through OracleAS TopLink Mapping Workbench:
There are several options you can set at login rather than through more conventional methods, such as through OracleAS TopLink Mapping Workbench.
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.
Example 5-6 Configuring Oracle Native Sequencing in Java Code
project.getLogin().useOracle(); project.getLogin().useNativeSequencing(); project.getLogin().setSequencePreallocationSize(1);
For more information, see "Sequencing".
By default, OracleAS TopLink loads a JDBC driver and connects to a database as follows:
To load and initialize the class, OracleAS TopLink calls
To obtain a connection, OracleAS TopLink calls
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
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
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