Annotation Type DataSourceDefinition
-
@Target(TYPE) @Retention(RUNTIME) @Repeatable(DataSourceDefinitions.class) public @interface DataSourceDefinition
Annotation used to define a containerDataSource
to be registered with JNDI. TheDataSource
may be configured by setting the annotation elements for commonly usedDataSource
properties. Additional standard and vendor-specific properties may be specified using theproperties
element.The data source will be registered under the name specified in the
name
element. It may be defined to be in any valid Jakarta EE namespace, which will determine the accessibility of the data source from other components.A JDBC driver implementation class of the appropriate type, either
DataSource
,ConnectionPoolDataSource
, orXADataSource
, must be indicated by theclassName
element. The availability of the driver class will be assumed at runtime.DataSource properties should not be specified more than once. If the url annotation element contains a DataSource property that was also specified using the corresponding annotation element or was specified in the properties annotation element, the precedence order is undefined and implementation specific:
@DataSourceDefinition(name="java:global/MyApp/MyDataSource", className="org.apache.derby.jdbc.ClientDataSource", url="jdbc:derby://localhost:1527/myDB;user=bill", user="lance", password="secret", databaseName="testDB", serverName="luckydog" )// DO NOT DO THIS!!!
In the above example, the
databaseName
,user
andserverName
properties were specified as part of theurl
property and using the corresponding annotation elements. This should be avoided.If the
properties
annotation element is used and contains a DataSource property that was also specified using the corresponding annotation element, the annotation element value takes precedence. For example:@DataSourceDefinition(name="java:global/MyApp/MyDataSource", className="org.apache.derby.jdbc.ClientDataSource", user="lance", password="secret", databaseName="testDB", serverName="luckydog", properties= {"databaseName=myDB", "databaseProp=doThis"} )// DO NOT DO THIS!!!
This would result in the following values being used when configuring the DataSource:
- serverName=luckydog
- portNumber=1527
- databaseName=testDB
- user=lance
- password=secret
- databaseProp=doThis
Vendors are not required to support properties that do not normally apply to a specific data source type. For example, specifying the
transactional
property to betrue
but supplying a value forclassName
that implements a data source class other thanXADataSource
may not be supported.Vendor-specific properties may be combined with or used to override standard data source properties defined using this annotation.
DataSource
properties that are specified and are not supported in a given configuration or cannot be mapped to a vendor specific configuration property may be ignored.Examples:
@DataSourceDefinition(name="java:global/MyApp/MyDataSource", className="com.foobar.MyDataSource", portNumber=6689, serverName="myserver.com", user="lance", password="secret" )
Using a
URL
:
@DataSourceDefinition(name="java:global/MyApp/MyDataSource", className="org.apache.derby.jdbc.ClientDataSource", url="jdbc:derby://localhost:1527/myDB", user="lance", password="secret" )
An example lookup of the DataSource from an Jakarta Enterprise Beans:
@Stateless public class MyStatelessEJB { @Resource(lookup="java:global/MyApp/myDataSource") DataSource myDB; ... }
- Since:
- Common Annotations 1.1
- See Also:
DataSource
,XADataSource
,ConnectionPoolDataSource
-
-
Required Element Summary
Required Elements Modifier and Type Required Element Description String
className
Name of a DataSource class that implementsjavax.sql.DataSource
orjavax.sql.XADataSource
orjavax.sql.ConnectionPoolDataSource
.String
name
JNDI name by which the data source will be registered.
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description String
databaseName
Name of a database on a server.String
description
Description of this data sourceint
initialPoolSize
Number of connections that should be created when a connection pool is initialized.int
isolationLevel
Isolation level for connections.int
loginTimeout
Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.int
maxIdleTime
The number of seconds that a physical connection should remain unused in the pool before the connection is closed for a connection pool.int
maxPoolSize
Maximum number of connections that should be concurrently allocated for a connection pool.int
maxStatements
The total number of statements that a connection pool should keep open.int
minPoolSize
Minimum number of connections that should be allocated for a connection pool.String
password
Password to use for connection authentication.int
portNumber
Port number where a server is listening for requests.String[]
properties
Used to specify vendor-specific properties and less commonly usedDataSource
properties such as:String
serverName
Database server name.boolean
transactional
Set tofalse
if connections should not participate in transactions.String
url
A JDBC URL.String
user
User name to use for connection authentication.
-
-
-
Element Detail
-
name
String name
JNDI name by which the data source will be registered.- Since:
- 1.1
-
-
-
className
String className
Name of a DataSource class that implementsjavax.sql.DataSource
orjavax.sql.XADataSource
orjavax.sql.ConnectionPoolDataSource
.- Since:
- 1.1
-
-
-
description
String description
Description of this data source- Since:
- 1.1
- Default:
- ""
-
-
-
url
String url
A JDBC URL. If theurl
annotation element contains a DataSource property that was also specified using the corresponding annotation element, the precedence order is undefined and implementation specific.- Since:
- 1.1
- Default:
- ""
-
-
-
user
String user
User name to use for connection authentication.- Since:
- 1.1
- Default:
- ""
-
-
-
password
String password
Password to use for connection authentication.- Since:
- 1.1
- Default:
- ""
-
-
-
databaseName
String databaseName
Name of a database on a server.- Since:
- 1.1
- Default:
- ""
-
-
-
serverName
String serverName
Database server name.- Since:
- 1.1
- Default:
- "localhost"
-
-
-
isolationLevel
int isolationLevel
Isolation level for connections. The Isolation level must be one of the following:- Connection.TRANSACTION_NONE,
- Connection.TRANSACTION_READ_ UNCOMMITTED,
- Connection.TRANSACTION_READ_COMMITTED,
- Connection.TRANSACTION_REPEATABLE_READ,
- Connection.TRANSACTION_SERIALIZABLE
Default is vendor-specific.
- Since:
- 1.1
- Default:
- -1
-
-
-
properties
String[] properties
Used to specify vendor-specific properties and less commonly usedDataSource
properties such as:- dataSourceName
- networkProtocol
- propertyCycle
- roleName
Properties are specified using the format: propertyName=propertyValue with one property per array element.
If a DataSource property is specified in the
properties
element and the annotation element for the property is also specified, the annotation element value takes precedence.- Since:
- 1.1
- Default:
- {}
-
-
-
loginTimeout
int loginTimeout
Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout.Default is vendor-specific.
- Since:
- 1.1
- Default:
- 0
-
-