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 Java EE 7, DataSource resources were created administratively as described in Configuring WebLogic JDBC Resources in Administering JDBC Data Sources for Oracle WebLogic Server. Java 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. Java 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:
The javax.annotation.sql package provides @DataSourceDefinition
and @DataSourceDefinitions
for defining DataSource resource definitions in application component classes such as application clients, servlets, or Enterprise JavaBeans (EJB).
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 Java 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 the "Creating a DataSource using the @DataSourceDefinition Annotation" in the WebLogic Server Code Examples.
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> . . .
The Java 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 3-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 3-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() |
Learn about the implementation details to consider when creating and using DataSource resource definitions.
This section provides information on Data Source naming conventions:
Note:
Pre-WebLogic Server 12.1.1 and Java EE Data Source naming conventions are compatible. Existing applications do not need to change naming conventions to upgrade from previous releases.
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
The following conventions are used to name Java 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 Java EE names begin with java:
Table 3-2 provides information on how to map Java EE DataSource Resource definition elements to WebLogic Server resources.
Table 3-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 |
int portNumber() |
-1 |
Used to generate URL; added to |
String serverName() |
"localhost" |
Used to generate URL; added to |
int isolationLevel() |
-1 |
Sets |
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 |
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.
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: mypassword {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;
Consider the following when using a Java 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 Java 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
WebLogic Server allows you to implement Java EE data sources in a Java 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.
Learn about additional resources for review when implementing data source resource definitions.
Section EE.5.17 "DataSource Resource Definition" in the Java EE 7 Specification at http://jcp.org/en/jsr/detail?id=316.
The Java EE 7 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/.
JDBC™ 4.1 Specification at http://download.oracle.com/otn-pub/jcp/jdbc-4_1-mrel-spec/jdbc4.1-fr-spec.pdf
.
WebLogic Server Code Examples.