1. Developing JDBC Applications for Oracle WebLogic Server
  2. Using DataSource Resource Definitions

2 Using DataSource Resource Definitions

Data source resources are used to define a set of properties required to identify and access a database through the JDBC API. Learn how to create and use Jakarta EE DataSource resource definitions.
  • Using Jakarta EE DataSource Resource Definitions
    Data source resources are used to define a set of properties required to identify and access a database through the JDBC API. These properties include information such as the URL of the database server, the name of the database, and the network protocol to use to communicate with the server.
  • Using WebLogic Configuration Attributes
    The Jakarta EE 7 Definition annotation @DataSourceDefinition provides a basic standard set of configuration attributes. Oracle extends support for WebLogic Server's rich set of configuration attributes by supporting proprietary attributes using the property element.
  • Implementation Considerations When Using DataSource Resource Definitions
    Learn about the implementation details to consider when creating and using DataSource resource definitions.
  • Using Data Sources in Clients
    WebLogic Server allows you to implement Jakarta EE data sources in a Jakarta EE client with some limitations.
  • Additional Resources
    Learn about additional resources for review when implementing data source resource definitions.

Using Jakarta EE DataSource Resource Definitions

Data source resources are used to define a set of properties required to identify and access a database through the JDBC API. These properties include information such as the URL of the database server, the name of the database, and the network protocol to use to communicate with the server. You can declare data source definitions by creating data source resource definitions using annotations or deployment descriptor.

DataSource objects are registered with the Java Naming and Directory Interface (JNDI) naming service so that applications can use the JNDI API to access a DataSource object to make a connection with a database.

Prior to Jakarta EE 7, DataSource resources were created administratively as described in Configuring WebLogic JDBC Resources in Administering JDBC Data Sources for Oracle WebLogic Server. Jakarta EE 7 provides the option to programmatically define DataSource resources for a more flexible and portable method of database connectivity.

The name element uniquely identifies a DataSource and is registered with JNDI. The value specified in the name element begins with a namespace scope. Jakarta EE 7 includes the following scopes:

  • java:comp—Names in this namespace have per-component visibility.

  • java:module—Names in this namespace are shared by all components in a module, for example, the EJB components defined in an a ejb-jar.xml file.

  • java:app—Names in this namespace are shared by all components and modules in an application, for example, the application-client, web, and EJB components in an .ear file.

  • java:global—Names in this namespace are shared by all the applications in the server.

You can programmatically declare data source definitions using one of the following methods:

Parent topic: Using DataSource Resource Definitions

Creating DataSource Resource Definitions Using Annotations

The javax.annotation.sql package provides @DataSourceDefinition and @DataSourceDefinitions for defining DataSource resource definitions in application component classes such as application clients, servlets, or Jakarta Enterprise Beans (EJBs).

When the DataSource resource is injected, a DataSource object is created and registered with JNDI. Use annotation elements to configure the DataSource object. You can specify additional Jakarta EE and WebLogic configuration attributes in the properties element of the annotation. See Using WebLogic Configuration Attributes.

Use @DataSourceDefinition to create a single datasource definition. For example: 

. . .

@DataSourceDefinition(
name = "java:module/ExampleDS",
     className = "org.apache.derby.jdbc.ClientDataSource",
     portNumber = 1527,
     serverName = "localhost",
     databaseName = "exampleDB",
     user = "examples",
     password = "examples",
     properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"})

@WebServlet("/dataSourceServlet")
public class DataSourceServlet extends HttpServlet {
 
 . . .
 
  @Resource(lookup = "java:module/ExampleDS")

. . .

Use the @DataSourceDefinitions to create multiple datasource definitions. For example: 

. . .

@DataSourceDefinitions(
      value = {
 
        @DataSourceDefinition(name = "java:app/env/DS1",
           minPoolSize = 0,
           initialPoolSize = 0,
           className = "org.apache.derby.jdbc.ClientXADataSource",
           portNumber = 1527,
           serverName = "localhost",
           user = "examples",
           password = "examples",
           databaseName = "exampleDB",
           properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"}
                   ),
 
        @DataSourceDefinition(name = "java:comp/env/DS2",
           minPoolSize = 0,
           initialPoolSize = 0,
           className = "org.apache.derby.jdbc.ClientDataSource",
           portNumber = 1527,
           serverName = "localhost",
           user = "examples",
           password = "examples",
           databaseName = "examplesDB",
           properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"}
        )
      }
   )

. . .

For a complete example, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server.

Parent topic: Using Jakarta EE DataSource Resource Definitions

Creating DataSource Resource Definitions Using Deployment Descriptors

You can create DataSource resource definitions using deployment descriptors in application.xml, application-client.xml, web.xml, and ejb-jar.xml files. For example: 

. . .

 <data-source>
     <name>java:module/ExampleDS</name>
     <class-name>org.apache.derby.jdbc.ClientDataSource</class-name>
     <server-name>localhost</server-name>
     <port-number>1527</port-number>
     <database-name>exampleDB</database-name>
     <user>examples</user>
     <password>examples</password>
     <property>
       <name>create</name>
       <value>true</value>
     </property>
     <property>
       <name>weblogic.TestTableName</name>
       <value>SQL SELECT 1 FROM SYS.SYSTABLES</value>
     </property>
   </data-source>
. . .

Parent topic: Using Jakarta EE DataSource Resource Definitions

Using WebLogic Configuration Attributes

The Jakarta EE 7 Definition annotation @DataSourceDefinition provides a basic standard set of configuration attributes. Oracle extends support for WebLogic Server's rich set of configuration attributes by supporting proprietary attributes using the property element.

Note:

Consider the following limitations when using WebLogic Server proprietary attributes in the property element. WebLogic Server proprietary attributes:

  • Cannot be used to configure a Multi data source. It is not possible to embed a Multi data source in a EAR or WAR file.

  • Do not overlap @DataSourceDefinition annotation elements.

  • Do not include the data source level attributes name and version.

Table 2-1 summarizes WebLogic Server's extended support for Data Source configuration attributes by mapping Weblogic.Attribute Name property values to WebLogic configuration elements. For an example of a DataSource resource definition using WebLogic configuration elements, see Configuring Active GridLink DataSource Resource Definitions.

Table 2-1 WebLogic Configuration Attributes

Weblogic.Attribute Name WebLogic Element

AffinityPolicy

JDBCOracleParams.setAffinityPolicy()

AlgorithmType

JDBCDataSourceParams.setAlgorithmType()

CapacityIncrement

JDBCConnectionPoolParams.setCapacityIncrement()

ConnectionCreationRetryFrequencySeconds

JDBCConnectionPoolParams.setConnectionCreationRetryFrequencySeconds()

ConnectionPoolFailoverCallbackHandler

JDBCDataSourceParams.setConnectionPoolFailoverCallbackHandler()

ConnectionReserveTimeoutSeconds

JDBCConnectionPoolParams.setConnectionReserveTimeoutSeconds()

CredentialMappingEnable

JDBCConnectionPoolParams.setCredentialMappingEnabled()

DataSourceList

JDBCDataSourceParams.setDataSourceList()

DriverInterceptor

JDBCConnectionPoolParams.setDriverInterceptor()

FailoverRequestIfBusy

JDBCDataSourceParams.setFailoverRequestIfBusy()

FanEnabled

JDBCOracleParams.setFanEnabled()

GlobalTransactionsProtocol

JDBCDataSourceParams.setGlobalTransactionsProtocol()

HighestNumWaiters

JDBCConnectionPoolParams.setHighestNumWaiters()

IdentityBasedConnectionPoolingEnabled

JDBCConnectionPoolParams.setIdentityBasedConnectionPoolingEnabled()

IgnoreInUseConnectionsEnabled

JDBCConnectionPoolParams.setIgnoreInUseConnectionsEnabled()

InactiveConnectionTimeoutSeconds

JDBCConnectionPoolParams.setInactiveConnectionTimeoutSeconds()

InitSql

JDBCConnectionPoolParams.setInitSql()

JDBCXADebugLevel

JDBCConnectionPoolParams.setJDBCXADebugLevel()

KeepConnAfterLocalTx

JDBCDataSourceParams.setKeepConnAfterLocalTx()

KeepLogicalConnOpenOnRelease

JDBCXAParams.setKeepLogicalConnOpenOnRelease()

KeepXaConnTillTxComplete

JDBCXAParams.setKeepXaConnTillTxComplete()

LoginDelaySeconds

JDBCConnectionPoolParams.setLoginDelaySeconds()

NeedTxCtxOnClose

JDBCXAParams.setNeedTxCtxOnClose()

NewXaConnForCommit

JDBCXAParams.setNewXaConnForCommit()

OnsNodeList

JDBCOracleParams.setOnsNodeList()

OnsWalletFile

JDBCOracleParams.setOnsWalletFile()

OnsWalletPassword

JDBCOracleParams.setOnsWalletPassword()

OracleOptimizeUtf8Conversion

JDBCOracleParams.setOracleOptimizeUtf8Conversion()

PasswordEncrypted

JDBCDriverParams.setPassword

PinnedToThread

JDBCConnectionPoolParams.setPinnedToThread()

ProfileHarvestFrequencySeconds

JDBCConnectionPoolParams.setProfileHarvestFrequencySeconds()

ProfileType

JDBCConnectionPoolParams.setProfileType()

RecoverOnlyOnce

JDBCXAParams.setRecoverOnlyOnce()

RemoveInfectedConnections

JDBCConnectionPoolParams.setRemoveInfectedConnections()

ResourceHealthMonitoring

JDBCXAParams.setResourceHealthMonitoring()

RollbackLocalTxUponConnClose

JDBCXAParams.setRollbackLocalTxUponConnClose()

RowPrefetch

JDBCDataSourceParams.setRowPrefetch()

RowPrefetchSize

JDBCDataSourceParams.setRowPrefetchSize()

SecondsToTrustAnIdlePoolConnection

JDBCConnectionPoolParams.setSecondsToTrustAnIdlePoolConnection()

ShrinkFrequencySeconds

JDBCConnectionPoolParams.setShrinkFrequencySeconds()

StatementCacheSize

JDBCConnectionPoolParams.setStatementCacheSize()

StatementCacheType

JDBCConnectionPoolParams.setStatementCacheType()

StatementTimeout

JDBCConnectionPoolParams.setStatementTimeout()

StreamChunkSize

JDBCDataSourceParams.setStreamChunkSize()

TestConnectionsOnReserve

JDBCConnectionPoolParams.setTestConnectionsOnReserve()

TestFrequencySeconds

JDBCConnectionPoolParams.setTestFrequencySeconds()

TestTableName

JDBCConnectionPoolParams.setTestTableName()

UsePasswordIndirection

JDBCDriverParams.setUsePasswordIndirection()

UseXaDataSourceInterface

JDBCDriverParams.setUseXaDataSourceInterface()

WrapTypes

JDBCConnectionPoolParams.setWrapTypes()

XaEndOnlyOnce

JDBCXAParams.setXaEndOnlyOnce()

XaRetryDurationSeconds

JDBCXAParams.setXaRetryDurationSeconds()

XaRetryIntervalSeconds

JDBCXAParams.setXaRetryIntervalSeconds()

XaSetTransactionTimeout

JDBCXAParams.setXaSetTransactionTimeout()

XaTransactionTimeout

JDBCXAParams.setXaTransactionTimeout()

Parent topic: Using DataSource Resource Definitions

Implementation Considerations When Using DataSource Resource Definitions

Learn about the implementation details to consider when creating and using DataSource resource definitions.

Parent topic: Using DataSource Resource Definitions

Naming Conventions

This section provides information on Data Source naming conventions:

Note:

Pre-WebLogic Server 12.1.1 and Jakarta EE Data Source naming conventions are compatible. Existing applications do not need to change naming conventions to upgrade from previous releases.

Parent topic: Implementation Considerations When Using DataSource Resource Definitions

WebLogic Data Source Naming Conventions

The following conventions are used when naming Data Sources in releases prior to WebLogic Server 12.1.1:

  • dsname - The system resource JDBC descriptor (config/jdbc/*-jdbc.xml)

  • application@null@dsname - deprecated (pre-9.x), application-scoped JDBC descriptor in EAR

  • application@module@dsname - application-scoped, packaged JDBC descriptor in EAR

Parent topic: Naming Conventions

Jakarta EE Data Source Naming Conventions

The following conventions are used to name Jakarta EE Data Sources:

  • appname@modulename@componentname@dsname - Component level

  • appname@modulename@dsname - Module level

  • appname@dsname - Application level

  • dsname – Global

These names are compatible with earlier names because the Jakarta EE names begin with java:

Parent topic: Naming Conventions

Mapping the Jakarta EE DataSource Resource Definition to WebLogic Data Source Resources

Table 2-2 provides information on how to map Jakarta EE DataSource Resource definition elements to WebLogic Server resources.

Table 2-2 Mapping a DataSource Resource Definition to WebLogic Server Resources

DataSourceBean Default Value WebLogic Resource

String name()

Required

JDBCDataSourceParamsBean.setJndiName

String className()

Required

JDBCDriverParamsBean.setDriverName

String description()

""

Not Used

String url()

""

JDBCDriverParamsBean.setUrl

String user()

""

Added to JDBCDriverParamsBean.getProperties()

String password()

""

JDBCDriverParamsBean.setPassword

String databaseName()

""

Used to generate URL; added to properties

int portNumber()

-1

Used to generate URL; added to properties

String serverName()

"localhost"

Used to generate URL; added to properties

int isolationLevel()

-1

Sets desiredtxisolevel property which WebLogic Server uses to call Connection.setTransactionIsolation()

boolean transactional()

true

Used to generate URL

int initialPoolSize()

-1

JDBCConnectionPoolParamsBean.setInitialCapacity

int maxPoolSize()

-1

JDBCConnectionPoolParamsBean.setMaxCapacity

int minPoolSize()

-1

JDBCConnectionPoolParamsBean.setMinCapacity (new)

int maxIdleTime()

-1

JDBCConnectionPoolParamsBean.setShrinkFrequencySeconds

int maxStatements()

-1

JDBCConnectionPoolParamsBean.setStatementCacheSize

String[] properties()

{}

JDBCPropertiesBean

int loginTimeout()

0

Not Used

Parent topic: Implementation Considerations When Using DataSource Resource Definitions

Configuring Active GridLink DataSource Resource Definitions

An Active GridLink Data Source is defined by using the following name/value pair within the DataSource resource definition:

  • FanEnabled is set to true

  • OnsNodeList is a non-null value. A comma-separated list of ONS daemon listen addresses and ports for receiving ONS-based FAN events. See ONS Client Configuration in Administering JDBC Data Sources for Oracle WebLogic Server.

The following example shows a DataSource resource definition for an Active GridLink Data Source using deployment descriptors:

. . .

 <data-source>
    <name>java:global/DSD2</name>
    <class-name>oracle.jdbc.OracleDriver</class-name>
    <url>jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=lcr01155-r)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=mydb)))</url>
    <user>lefty123</user>
    <password>password</password>
    <property><name>weblogic.CapacityIncrement</name><value>2</value></property>
 <property><name>weblogic.HighestNumWaiters</name><value>2147483647</value></property>
    <property><name>weblogic.ConnectionCreationRetryFrequencySeconds</name><value>0</value></property>
    <property><name>weblogic.ConnectionReserveTimeoutSeconds</name><value>10</value></property>
    <property><name>weblogic.TestFrequencySeconds</name><value>120</value></property>
    <property><name>weblogic.TestConnectionsOnReserve</name><value>false</value></property>
    <property><name>weblogic.ProfileHarvestFrequencySeconds</name><value>300</value></property>
    <property><name>weblogic.IgnoreInUseConnectionsEnabled</name><value>true</value></property>
    <property><name>weblogic.InactiveConnectionTimeoutSeconds</name><value>0</value></property>
    <property><name>weblogic.TestTableName</name><value></value></property>
    <property><name>weblogic.LoginDelaySeconds</name><value>0</value></property>
    <property><name>weblogic.InitSql</name><value></value></property>
    <property><name>weblogic.StatementCacheType</name><value>LRU</value></property>
    <property><name>weblogic.RemoveInfectedConnections</name><value>true</value></property>
    <property><name>weblogic.SecondsToTrustAnIdlePoolConnection</name><value>10</value></property>
    <property><name>weblogic.StatementTimeout</name><value>-1</value></property>
    <property><name>weblogic.ProfileType</name><value>0</value></property>
    <property><name>weblogic.JDBCXADebugLevel</name><value>10</value></property>
    <property><name>weblogic.CredentialMappingEnabled</name><value>false</value></property>
    <property><name>weblogic.DriverInterceptor</name><value></value></property>
    <property><name>weblogic.PinnedToThread</name><value>false</value></property>
    <property><name>weblogic.IdentityBasedConnectionPoolingEnabled</name><value>false</value></property>
    <property><name>weblogic.WrapTypes</name><value>true</value></property>
    <property><name>weblogic.ConnectionLabelingCallback</name><value></value></property>
    <property><name>weblogic.FatalErrorCodes</name><value></value></property>
    <property><name>weblogic.Scope</name><value>Global</value></property>
    <property><name>weblogic.RowPrefetch</name><value>false</value></property>
    <property><name>weblogic.RowPrefetchSize</name><value>48</value></property>
    <property><name>weblogic.StreamChunkSize</name><value>256</value></property>
    <property><name>weblogic.AlgorithmType</name><value>Failover</value></property>
    <property><name>weblogic.ConnectionPoolFailoverCallbackHandler</name><value></value></property>
    <property><name>weblogic.FailoverRequestIfBusy</name><value>false</value></property>
    <property><name>weblogic.GlobalTransactionsProtocol</name><value>OnePhaseCommit</value></property>
    <property><name>weblogic.KeepConnAfterLocalTx</name><value>true</value></property>
    <property><name>weblogic.KeepConnAfterGlobalTx</name><value>false</value></property>
    <property><name>weblogic.UseXaDataSourceInterface</name><value>true</value></property>
    <property><name>weblogic.UsePasswordIndirection</name><value>false</value></property>
    <property><name>weblogic.FanEnabled</name><value>true</value></property>
    <property><name>weblogic.OnsNodeList</name><value>lcr01155-r:6200</value></property>
    <property><name>weblogic.OnsWalletFile</name><value></value></property>
    <property><name>weblogic.OnsWalletPassword</name><value></value></property>
    <property><name>weblogic.OracleOptimizeUtf8Conversion</name><value>false</value></property>
    <property><name>weblogic.ConnectionInitializationCallback</name><value></value></property>
    <property><name>weblogic.AffinityPolicy</name><value>Session</value></property>
    <property><name>weblogic.OracleProxySession</name><value>false</value></property>
    <property><name>weblogic.KeepXaConnTillTxComplete</name><value>true</value></property>
    <property><name>weblogic.NeedTxCtxOnClose</name><value>false</value></property>
    <property><name>weblogic.XaEndOnlyOnce</name><value>false</value></property>
    <property><name>weblogic.NewXaConnForCommit</name><value>false</value></property>
    <property><name>weblogic.KeepLogicalConnOpenOnRelease</name><value>false</value></property>
    <property><name>weblogic.ResourceHealthMonitoring</name><value>true</value></property>
    <property><name>weblogic.RecoverOnlyOnce</name><value>false</value></property>
    <property><name>weblogic.XaSetTransactionTimeout</name><value>false</value></property>
    <property><name>weblogic.XaTransactionTimeout</name><value>0</value></property>
    <property><name>weblogic.RollbackLocalTxUponConnClose</name><value>false</value></property>
    <property><name>weblogic.XaRetryDurationSeconds</name><value>0</value></property>
    <property><name>weblogic.XaRetryIntervalSeconds</name><value>60</value></property>
  </data-source>
. . .

For additional information, see Using Active GridLink Data Sources in Administering JDBC Data Sources for Oracle WebLogic Server.

Parent topic: Implementation Considerations When Using DataSource Resource Definitions

Using an Encrypted Password in a DataSourceDefinition

You can provide an encrypted password in the DataSourceDefinition. To do so you need to generate the password as shown in the following example, and then copy it into the DataSourceDefinition: 

# needs to be run in the domain home directory
java weblogic.security.Encrypt
Password:  user_password
{AES}OQ1CnXWsgTVQsxrHqpxMT7iZwt7wBBIrkLP5NWeAvNk="
# This value needs to be pasted into the DataSourceDefinition

The encrypted password is domain specific. If you use an encrypted password that does not match the domain, it will generate an error such as:

weblogic.application.ModuleException: com.rsa.jsafe.JSAFE_PaddingException:
 Invalid padding.:com.rsa.jsafe.JSAFE_PaddingException:Invalid padding

The following code fragment defines a data source using an encrypted password in an annotation in a Java servlet.

@DataSourceDefinition(
name="java:comp/ds",
className="oracle.jdbc.OracleDriver",
portNumber=1521,
serverName="myhost",
user="myuser",
databaseName="mydbname",
initialPoolSize = 0,
minPoolSize = 0,
maxPoolSize = 15,
maxStatements = 0,
transactional=false,
properties = {"weblogic.TestTableName=SQL ISVALID",
 "weblogic.PasswordEncrypted={AES}OQ1CnXWsgTVQsxrHqpxMT7iZwt7wBBIrkLP5NWeAvNk="}
)
@WebServlet(urlPatterns = "/GetVersion")
public class GetVersion extends javax.servlet.http.HttpServlet
  implements javax.servlet.Servlet {
  @Resource(lookup = "java:comp/ds")
  private DataSource ds;

Parent topic: Implementation Considerations When Using DataSource Resource Definitions

Additional Considerations

Consider the following when using a Jakarta EE DataSource resource definition with WebLogic Server:

  • If an annotation and a descriptor have the same DataSource name in the same scope, the attributes are merged with values specified in the deployment descriptor. The deployment descriptor value takes precedence over values specified in a annotation.

  • A DataSource is not a module, it is a resource created as part of a module.

  • A DataSource is not a JDBCSystemResources object associated with a domain and is not in the WebLogic Server configuration bean tree.

  • You can use the JSR88 API's to view applications that include Jakarta EE 7 Data Sources.

  • There is one runtime MBean created for each datasource definition. The name of the MBean is the decorated name.

  • WLS has a limited set of known class names for which it can generate a URL. For the non-XA case, the JDBC driver and not the datasource class is often known. An error occurs when an unknown class name is specified with a databaseName, portNumber, and/or serverName. In this case, remove databaseName, portNumber, serverName, and specify the URL.

  • URL generation is not supported for AGL data sources.

  • URL generation in general is a problem for all Oracle drivers because of the service, database, and Oracle RAC instance formats. The best practice is to provide the URL for Oracle drivers

Parent topic: Implementation Considerations When Using DataSource Resource Definitions

Using Data Sources in Clients

WebLogic Server allows you to implement Jakarta EE data sources in a Jakarta EE client with some limitations.

The limitations are as follows:

  • Transactional=true is not supported. The transaction protocol is set to NONE.

  • Data Sources that are global or application in scope are visible (created) both on the client and the server. This has the downside of using more connections.

  • No permission checking is performed on a Data Source. Operations such as reserve and shrink can be used on a local Data Source.

Parent topic: Using DataSource Resource Definitions

Additional Resources

Learn about additional resources for review when implementing data source resource definitions.

Parent topic: Using DataSource Resource Definitions