One of the most important functions of a session is to provide access to a data source. This chapter explains session components specific to accessing a data source.
This chapter includes the following sections:
This section describes concepts unique to TopLink data access, including the following:
A TopLink transactional data source is externally managed if the connection pool is managed by a transaction service (such as an application server controlled transaction or a JTA transaction). A JTA managed data source or connection pool is commonly used in Java EE applications and normally required in EJB applications. Use an externally-managed connection pool as follows:
Configure the session to use an ExternalTransactionController to integrate TopLink's unit of work with the external transaction service (see Section 115.13, "Integrating the Unit of Work with an External Transaction Service").
Use the external-transaction-control option to specify the connection's login and inform TopLink that the connection is maintained by the external controller (see Section 97.4, "Configuring External Connection Pooling").
You may need to configure the TopLink read connection pool or sequence connection pool to use a non-JTA connection pool in order to avoid transactional overhead (see Section 96.1.6.3, "Default (Write) and Read Connection Pools").
For more information on transactional data sources, see the following:
Refer to Chapter 113, "Introduction to TopLink Transactions" for more information on TopLink transactions.
The login (if any) associated with a session determines how the TopLink runtime connects to the project's data source.
A login includes details of data source access, such as authentication, use of connection pools, and use of external transaction controllers. A Login owns a data source platform.
A data source platform includes options specific to a particular data source including such as binding, use of native SQL, use of batch writing, and sequencing. For more information about platforms, see Section 96.1.3, "Data Source Platform Types".
For projects that do not persist to a data source, a login is not required. For projects that do persist to a data source, a login is always required.
In TopLink Workbench, the project type determines the type of login that the project uses, if applicable.
You can use a login in a variety of roles. A login's role determines where and how you create it. The login role you choose depends on the type of project you are creating and how you intend to use the login, as follows:
There is a session login type for each project type that persists to a data source. The following are the types:
Note that there is no XML login. TopLink XML projects are used for nonpersistent, in-memory object to XML data transformation and consequently there is no data source to log in to. For more information about persistent and nonpersistent projects, see Section 15.2.3, "Persistent and Nonpersistent Projects".
For additional information, see the following:
If you are creating a project that accesses a relational database, you must configure the project with a DatabaseLogin. Your choice of DatabasePlatform further customizes your project for a particular type of database (see Section 96.1.3.1, "Database Platforms").
For more information, see Section 98.1, "Introduction to Database Login Configuration".
If you are creating a project that accesses a nonrelational data source using a JCA adapter, you must configure the project with an EISLogin. Your choice of EISPlatform further customizes your project for a particular JCA adapter and specifies what record type TopLink uses to exchange data with the EIS (see Section 96.1.3.2, "EIS Platforms").
For more information, see Section 99.1, "Introduction to EIS Login Configuration".
TopLink abstracts the details of your underlying data source using data source platform classes. TopLink provides the following data source platforms:
A data source platform is owned by your project's Login. For more information about logins, see Section 96.1.2, "Data Source Login Types".
To configure most platform options, you must use an amendment method (see Section 119.35, "Configuring Amendment Methods"), or a preLogin event listener (see Section 87.2.5, "Managing Session Events with the Session Event Manager").
TopLink interacts with databases using structured query language (SQL). Because each database platform uses its own variation on the basic SQL language, TopLink must adjust the SQL it uses to communicate with the database to ensure that the application runs smoothly.
The type of database platform you choose determines the specific means by which the TopLink runtime accesses the database, including the type of Java Database Connectivity (JDBC) driver to use. JDBC is an application programming interface (API) that gives Java applications access to a database. TopLink relational projects rely on JDBC connections to read objects from, and write objects to, the database. TopLink applications use either individual JDBC connections or a JDBC connection pool (see Section 96.1.6, "Connection Pools"), depending on the application architecture.
TopLink provides a variety of database-specific platforms that let you customize your project for your target database.
Oracle Database platforms are located in oracle.toplink.platform.database.oracle package and include the following:
Oracle8Platform
Oracle9Platform
Oracle10Platform
Oracle11Platform
Non-Oracle Database platforms are located in oracle.toplink.platform.database package and include the following:
AccessPlatform for Microsoft Access databases
AttunityPlatform for Attunity Connect JDBC drivers
CloudscapePlatform
DB2MainframePlatform
DB2Platform
DBasePlatform
DerbyPlatform
HSQLPlatform
InformixPlatform
JavaDBPlatform
MySQL4Platform
PointBasePlatform
PostgreSQLPlatform
SQLAnyWherePlatform
SQLServerPlatform
SybasePlatform
TimesTen7Platform for TimesTen 7 database
Specify your database platform at the project level (see Section 20.2, "Configuring Relational Database Platform at the Project Level") for all sessions, or override this project-level configuration at the session level (see Section 98.2, "Configuring a Relational Database Platform at the Session Level").
If you set your database platform in TopLink Workbench, then TopLink Workbench manages the database platform configuration for you automatically.
TopLink interacts with an EIS data source indirectly by way of a JCA adapter. TopLink abstracts the details of an EIS data source using the oracle.toplink.eis.EISPlatform class.
The type of EIS platform you choose determines the specific means by which the TopLink runtime accesses the EIS, including the type of JCA adapter to use. TopLink EIS projects rely on EIS connections to read objects from, and write objects to, the EIS. TopLink applications use individual EIS connections returned by the EIS connection factory specified by the EIS platform.
TopLink provides a variety of EISPlaform classes that let you customize your project for your target EIS.
EIS platforms for production are located in oracle.toplink.eis.adapters package and include the following:
oracle.toplink.eis.adapters.aq.AQPlatform to access an EIS using Oracle Advanced Queuing messages.
oracle.toplink.eis.adapters.attunity.AttunityPlatform to access an EIS using an Attunity JCA adapter.
oracle.toplink.eis.adapters.jms.JMSPlatform to access an EIS using JMS messages.
oracle.toplink.eis.adapters.mqseries.MQPlatform to access an EIS using IBM MQSeries messages.
EIS platforms for testing are also located in oracle.toplink.eis.adapters and include the following:
oracle.toplink.eis.adapters.blackbox.BlackBoxPlatform for testing your EIS project with the Sun BlackBox reference adapter using indexed records only.
oracle.toplink.eis.adapters.xmlfile.XMLFilePlatform for testing your EIS project with an EIS emulated as one or more XML files in the local file system using XML records.
Specify your EIS platform at the session level (see Section 99.2, "Configuring an EIS Data Source Platform at the Session Level").
If you set your platform in TopLink Workbench, then TopLink Workbench manages the EIS platform configuration for you automatically.
Authentication is the means by which a data source validates a user's identity and determines whether or not the user has sufficient privileges to perform a given action.
For two-tier applications, simple JDBC authentication is usually sufficient (see Section 96.1.4.1, "Simple JDBC Authentication").
For three-tier applications, you can use simple JDBC authentication or, proxy authentication (see Section 96.1.4.2, "Oracle Database Proxy Authentication") when using the Oracle Call Interface (OCI) JDBC driver.
Authentication plays a central role in data security and user accountability and auditing (see Section 96.1.4.3, "Auditing").
When you configure a TopLink database login with a user name and password (Section 97.2, "Configuring User Name and Password"), TopLink provides these credentials to the JDBC driver that you configure your application to use (see Section 98.3, "Configuring Database Login Connection Options").
By default, TopLink writes passwords to and reads them from the sessions.xml file in encrypted form using JCE encryption. Optionally, you can configure a different encryption class (see Section 97.3, "Configuring Password Encryption").
TopLink supports proxy authentication with Oracle Database in JSE applications and JEE applications using OC4J native or managed data sources with Oracle JDBC driver release 10.1.0.2.0 or later and external connection pools (see Section 96.1.6.2, "External Connection Pools") only.
Note:
TopLink does not support Oracle Database proxy authentication with JTA.Oracle Database proxy authentication delivers the following security benefits:
A limited trust model, by controlling the users on whose behalf middle tiers can connect, and the roles the middle tiers can assume for the user.
Scalability, by supporting user sessions through Oracle Call Interface (OCI) and thick JDBC, and eliminating the overhead of reauthenticating clients.
Accountability, by preserving the identity of the real user through to the database, and enabling auditing of actions taken on behalf of the real user.
Flexibility, by supporting environments in which users are known to the database, and in which users are merely "application users" of which the database has no awareness.
Note:
Oracle Database supports proxy authentication in three-tiers only; it does not support it across multiple middle tiers.For more information about authentication in Oracle Database, see "Preserving User Identity in Multitiered Environments" in the Oracle Database Security Guide.
Configure your TopLink database login to use proxy authentication (see Section 98.8, "Configuring Oracle Database Proxy Authentication") to do the following:
address the complexities of authentication in a three-tier architecture (such as client-to-middle-tier and middle-tier-to-database authentication, and client reauthentication through the middle -tier to the database)
enhance database audit information (for even triggers and stored procedures) by using a specific user for database operations, rather than the generic pool user
simplify VPD/OLS configuration (see Section 87.5.1, "Isolated Client Sessions and Oracle Virtual Private Database (VPD)") by using a proxy user, rather than setting user information directly in the session context with stored procedures
Regardless of what type of authentication you choose, TopLink logs the name of the user associated with all database operations. Example 96-1 shows the CONFIG level TopLink logs when a ServerSession connects through the main connection for the sample user "scott", and a ClientSession uses proxy connection "jeff".
Example 96-1 TopLink Logs with Oracle Database Proxy Authentication
[TopLink Config]--ServerSession(13)--Connection(14)--Thread(Thread[main,5,main])--connecting(DatabaseLogin( platform=>Oracle9Platform user name=> "scott" connector=>OracleJDBC10_1_0_2ProxyConnector datasource name=>DS)) [TopLink Config]--ServerSession(13)--Connection(34)--Thread(Thread[main,5,main])--Connected: jdbc:oracle:thin:@localhost:1521:orcl User: SCOTT [TopLink Config]--ClientSession(53)--Connection(54)--Thread(Thread[main,5,main])--connecting(DatabaseLogin(platform=>Oracle9Platform user name=> "scott" connector=>OracleJDBC10_1_0_2ProxyConnector datasource name=>DS)) [TopLink Config]--ClientSession(53)--Connection(56)--Thread(Thread[main,5,main])--Connected: jdbc:oracle:thin:@localhost:1521:orcl User: jeff
For more information on configuring TopLink log level and log options, see Section 89.4, "Configuring Logging".
Your database server likely provides additional user auditing options. Consult your database server documentation for details.
Alternatively, you may consider using the TopLink unit of work in conjunction with your database schema for auditing purposes (see Section 115.12, "Implementing User and Date Auditing with the Unit of Work").
A connection is an object that provides access to a data source by way of the driver you configure your application to use (see Section 98.3, "Configuring Database Login Connection Options"). Relational projects use JDBC to connect to the data source; EIS and XML projects use JCA. TopLink uses the interface oracle.toplink.internal.databaseaccess.Accessor to wrap data source connections. This interface is accessible from certain events (see Section 16.2.8, "Descriptor Event Manager").
Typically, when using a server session, TopLink uses a a different connection for both reading and writing. This lets you use nontransactional connections for reading and avoid maintaining connections when not required. See Section 115.15.1.4, "Reading Through the Write Connection" and Exclusive Write Connections for more information.
By default, a TopLink server session acquires connections lazily: that is, only during the commit operation of a unit of work. Alternatively, you can configure TopLink to acquire a write connections at the time you acquire a client sessions (see Lazy Connection Acquisition).
Connections can be allocated from internal or external connection pools (see Section 96.1.6, "Connection Pools").
A connection pool is a service that creates and maintains a shared collection (pool) of data source connections on behalf of one or more clients. The connection pool provides a connection to a process on request, and returns the connection to the pool when the process is finished using it. When it is returned to the pool, the connection is available for other processes. Because establishing a connection to a data source can be time-consuming, reusing such connections in a connection pool can improve performance.
TopLink uses connection pools to manage and share the connections used by server and client sessions. This feature reduces the number of connections required and allows your application to support many clients.
You can configure your session to use internal connection pools provided by TopLink or external connection pools provided by a JDBC driver or Java EE container.
You can use connection pools in your TopLink application for a variety of purposes, such as reading, writing, sequencing, and other application-specific functions.
This section describes the following:
For non-Java EE applications, you typically use internal connection pools. By default, TopLink sessions use internal connection pools.
Using internal connection pools, you can use TopLink Workbench to configure the default (write) and read connection pools (see Section 96.1.6.3, "Default (Write) and Read Connection Pools") and you can create additional connection pools for object identity (see Section 96.1.6.4, "Sequence Connection Pools"), or any other purpose (see Section 96.1.6.5, "Application-Specific Connection Pools").
Using internal connection pools, you can optimize the creation of read connections for applications that read data only to display it and only infrequently modify data (see Section 101.4, "Configuring a Nontransactional Read Login").
For information on selecting the type of connection pool to use, see Section 97.4, "Configuring External Connection Pooling".
For more information on creating and configuring internal connection pools, see the following:
For Java EE applications, you typically use external connection pools.
If you are using an external transaction controller (JTA), you must use external connection pools to integrate with the JTA (see Section 115.13, "Integrating the Unit of Work with an External Transaction Service").
Using external connection pools, you can use either TopLink Workbench or Java to configure the default (write) and read connection pools (see Section 96.1.6.3, "Default (Write) and Read Connection Pools") and create additional connection pools for object identity (see Section 96.1.6.4, "Sequence Connection Pools"), or any other purpose (see Section 96.1.6.5, "Application-Specific Connection Pools").
For more information on selecting the type of connection pool to use, see Section 97.4, "Configuring External Connection Pooling".
A server session provides a read connection pool and a write connection pool. These could be different pools, or if you use external connection pooling, the same connection pool.
All read queries use connections from the read connection pool and all queries that write changes to the data source use connections from the write connection pool. You can configure attributes of the default read and write connection pools.
Whenever a new connection is established, TopLink uses the connection configuration you specify in your session's DatasourceLogin. Alternatively, when you use an external transaction controller, you can define a separate connection configuration for a read connection pool to avoid the additional overhead, if appropriate (see Section 101.4, "Configuring a Nontransactional Read Login").
For more information on configuring read and write connection pools, see Section 101.1, "Introduction to the Internal Connection Pool Configuration".
An essential part of maintaining object identity (see Section 102.2.1, "Cache Type and Object Identity") is sequencing–managing the assignment of unique values to distinguish one instance from another. For more information, see Section 15.2.6, "Projects and Sequencing".
Sequencing involves reading and writing a special sequence resource maintained by your data source.
By default, TopLink includes sequence operations in a separate transaction. This avoids complications during the write transaction, which may lead to deadlocks over the sequence resource. However, when using an external transaction controller (such as a JTA data source or connection pool), TopLink cannot use a different transaction for sequencing. Use a sequence connection pool to configure a non-JTA transaction pool for sequencing. This is required only for table sequencing–not native sequencing.
In each server session, you can create one connection pool, called a sequence connection pool, that TopLink uses exclusively for sequencing. With a sequence connection pool, TopLink satisfies a request for a new object identifier outside of the transaction from which the request originates. This allows TopLink to immediately commit an update to the sequence resource, which avoids deadlocks.
Note:
If you use a sequence connection pool and the original transaction fails, the sequence operation does not roll back.You should use a sequence connection pool, if the following applies:
You use table sequencing (that is, non-native sequencing). See Section 18.2.2.1, "Table Sequencing" and Section 18.2.2.2, "Unary Table Sequencing" for more information.
You use external transaction controller (JTA).
You should not use a sequence connection pool, if the following applies:
You do not use sequencing, or use the data source's native sequencing (see 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").
You have configured the sequence table to avoid deadlocks.
You use non-JTA data sources.
For more information, see the following:
When you use internal TopLink connection pools in a session, you can create one or more connection pools that you can use for any application purpose. These are called named connection pools, as you can give them any name you want and use them for any purpose.
Typically, use these named connection pools to provide pools of different security levels. For example, the "default" connection pool may only allow access to specific tables but the "admin" connection pool may allow access to all tables.
For more information, see the following:
This section describes the following:
Example 96-2 illustrates the login types that are derived from abstract class oracle.toplink.sessions.DatasourceLogin.
Example 96-3 illustrates the platform type class hierarchy.
Example 96-3 Platform Inheritance Hierarchy
oracle.toplink.platform.database
AccessPlatform AttunityPlatform CloudscapePlatform DatabasePlatform DB2MainframePlatform DB2Platform DBasePlatform
Derbylatform
HSQLPlatform InformixPlatform
JavaDBPlatform
PointBasePlatform
PostgreeSQLPlatform
SQLAnyWherePlatform SQLServerPlatform SybasePlatform
TimesTen7Platform
oracle.toplink.platform.database.oracle
Oracle8Platform Oracle9Platform
Oracle10Platform Oracle11Platform
OraclePlatform