Oracle Application Server 10g Oracle Containers for J2EE Data Source

Frequently Asked Questions October 2005

This FAQ addresses frequently asked questions relating to the Data Source aspects of Oracle Application Server Containers for J2EE 10g (10.1.3) and is broken into the following sections:

What is a Data Source? What types of Data Sources do OC4J support in 10g (10.1.3)? What is a Managed Data Source? What is a Native Data Source? How do I define or create a Data Source? Are there examples for defining data sources? Can I modify a Data Source at run-time? Is connection pooling supported in OC4J data sources? How should I configure connection pooling for OC4J data sources? What if I don't want to put the database user password in clear text in a data sources definition? Do OC4J data sources support JTA global transactions? Can I use databases other than Oracle with OC4J? Is this supported? I have some data sources defined in the pre-10g (10.1.3) format, what should I do? Can I deploy a pre-configured data-sources.xml file along with my application?

What is a Data Source? A data source is a Java object that implements the javax.sql.DataSource interface. Data sources offer a portable, vendor-independent method for creating connections to databases. A data source object's properties are set so that it represents a particular database. An application can

Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ

Page 1

use a different database by changing the data source's properties; while no change in the application code is required. What types of Data Sources do OC4J support in 10g (10.1.3)? OC4J 10g (10.1.3) provides 2 types of data sources defined in 10g (10.1.3) format: managed data sources and native data sources. For backward compatibility, OC4J 10g (10.1.3) also supports 3 types of data sources defined in pre-10g (10.1.3) format: emulated data sources, nonemulated data sources, and native data sources. The latter 3 data source types, although still supported, are deprecated and will be desupported in a future release of OC4J. What is a Managed Data Source? A Managed data source is a data source that is managed by OC4J. This means that OC4J provides critical system infrastructure such as global transaction management, connection pooling, and error handling. A managed data source is an OC4J-provided implementation of the javax.sql.DataSource interface that acts as a wrapper to a JDBC driver or data source. J2EE components access managed data sources via JNDI with no knowledge that the data source implementation is a wrapper. Managed data sources differ from native data sources as follows: The connections retrieved from a managed data source can participate in global transactions. A managed data source makes use of OC4J's connection pool and statement cache. A connection returned from a managed data source is wrapped with an OC4J Connection proxy. What is a Native Data Source? A Native data source implements the javax.sql.DataSource interface and is provided by JDBC driver vendors (such as Oracle and DataDirect). Native data sources differ from managed data sources as follows: The connections retrieved from a native data source cannot participate in global transactions. A native data source does not make use of OC4J's connection pool or statement cache. A connection returned from a native data source is not wrapped with an OC4J Connection proxy. How do I define or create a Data Source? The primary tool to create, delete, and modify data sources is the Oracle Enterprise Manager 10g Application Server Control Console (Application Server Control Console). This tool provides user-friendly graphical guide to assist you in defining OC4J data sources. Data source definitions are persisted in an Enterprises Applications data-sources.xml file. Each <data-source> element in this file represents one data source that is bound into JNDI and therefore accessible from client components (servlets, EJBs, etc.). The default application's data sources configuration file is located in $J2EE_HOME/config/data-sources.xml. You can also define a data source manually by directly modifying the data-sources.xml file for an Enterprise Application, or modifying the data-sources.xml file at the default location Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ Page 2

above for globally shared use. See the Data Sources Chapter in the OC4J Services Guide for more information. Are there examples for defining data sources? Yes, definitely. The following example on Oracle Technology Network shows you how to define data sources using the Application Server Control Console: http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/how-to-asc-datasource/doc/howto-asc-datasource.html The following example on Oracle Technology Network shows you how to configure and use data sources in a manual way: http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/how-to-datasource/doc/how-todatasource.html Can I modify a Data Source at run-time? Yes, you can. Through the Application Server Control Console, OC4J provides full JMX support for managing data sources including operations to create data sources and connection pools, remove data sources and connection pools, and modify existing data sources and connection pools. When the data sources are modified in the Application Server Control Console, the data sources are immediately persisted to the data-sources.xml file for that application. However, note that a new data-sources.xml file is generated by the Application Server Control Console each time and comments are lost. Is connection pooling supported in OC4J data sources? Yes. A managed data source uses a connection pool to efficiently manage connections. If you will create managed data sources, you must define at least one connection pool and its connection factory. For native data sources, you can use a DataSource implementation that supports connection pooling/caching, like Oracle JDBCs oracle.jdbc.pool.OracleDataSource. How should I configure connection pooling for OC4J data sources? Connection pooling configuration is done in similar way of regular data source configuration. The recommended way is again to use the Application Server Control Console, while manual definition is also supported for direct data-sources.xml file modification. See the Data Sources Chapter in the OC4J Services Guide for more information. The following article on Oracle Technology Network explains connection pooling in OC4J 10g (10.1.3) data sources: http://www.oracle.com/technology/pub/notes/technote_ds_caching.html What if I don't want to put the database user password in clear text in a data sources definition? OC4J 10g (10.1.3) allows you to specify passwords used in its various configuration files in a secure manner through the use of password indirection. Password indirection allows you to specify the name of a user in a secure repository, from which OC4J will extract the password to use. This enables passwords to be maintained in a centralized location and allows the choice of using the local XML user store or the use of the Oracle Internet Directory. Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ Page 3

See the OC4J Services Guide of the OC4J documentation set for more information. Do OC4J data sources support JTA global transactions? This depends on the data source type: managed data sources support global transactions, while native data sources do not. You can also definitely configure managed data sources to support local transactions only. Can I use databases other than Oracle with OC4J? Is this supported? Yes. In fact, Oracle supplies a set of supported JDBC drivers that connect to databases from IBM, Sybase, and Microsoft. Using JDBC drivers other than those in the Oracle-supplied library is not supported. To establish a connection to a non-Oracle database, you configure a data source in OC4J that defines the JDBC driver to use and provides other required pieces of information such as the JDBC URL, connection names, etc. See the Data Sources chapter in the OC4J Services Guide of the OC4J documentation set for more information. I have some data sources defined in the pre-10g (10.1.3) format, what should I do? Data source migration is done in one of two ways: (1) you can simply use the datasources.xml file as it is, and OC4J will do the conversion for you at run-time; or (2) you can use the admin.jar tool with the convertDataSourceConfiguration option to manually convert the data-sources.xml into its corresponding 10g (10.1.3) format and then use it. See the Data Sources chapter in the OC4J Configuration and Administration Guide of the OC4J documentation set for more information. Can I deploy a pre-configured data-sources.xml file along with my application? Yes. You may package both security and datasource configuration files with your application archive (EAR) file. When the application is deployed, the files will be used by OC4J to establish connections or validate user credentials. This is a standard packaging mechanism employed by Oracle JDeveloper when it deploys applications. To achieve this, provide the files you want to accompany the deployment in the same directory as the J2EE application.xml file. In addition, provide an orion-application.xml file which contains references to the files you wish to deploy along with your application. Let's say you wish to include a data-sources.xml file with your application. The data-sources.xml will contain configuration information about which database this application must connect to. The EAR file should look like the following: <EAR-FILE> /META-INF application.xml orion-application.xml data-sources.xml webmodule.war ejbmodule.jar

Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ

Page 4

The orion-application.xml contains an entry to indicate that the local data-sources.xml file should be used. <orion-application> <data-sources path="./data-sources.xml"/> </orion-application> At deployment time, OC4J will use the contents of the orion-application.xml you provided as a template for the final version it generates. It will also copy the data-sources.xml file you specified from the EAR file into its deployment directory and use it as the data source configuration file for the application.

Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ

Page 5

Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ October 2005 Author: Frances Zhao Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com Copyright 2005, Oracle. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle, JD Edwards, PeopleSoft, and Retek are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Oracle, JD Edwards, PeopleSoft, and Retek are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Oracle Application Server Containers for J2EE 10g (10.1.3) FAQ

Page 6